Coop

Coop is a free platform for creating, storing and sharing AI-based research. It is fully integrated with EDSL, allowing you to post, store and retrieve any objects that you’ve created with EDSL, together with data, notebooks and other project content. You can also explore public content and collaborate on projects privately with other users:

View your content at the Coop

Your Coop account also provides access to features for running EDSL surveys and storing results remotely at the Expected Parrot server. Learn more about these features in the Remote Inference and Remote Caching sections of the documentation.

Getting started

1. Create an account

Sign up with an email address.

Your account comes with an Expected Parrot API key that allows you to:

  • Post and share content at Coop

  • Run surveys at the Expected Parrot server

  • Use any available models with your surveys

  • Use remote caching for your responses

You can inspect your key and reset it at any time at your Keys page:

Remote inference settings and Expected Parrot API key

2. Store your Expected Parrot API key

When remote inference is activated, your survey jobs and results are automatically stored at the Expected Parrot server and accessible at the Remote inference page of your account.

You can also post objects to Coop from your workspace, such as Surveys, Agents and Notebooks. To do this, you first need to store your Expected Parrot API key. If you have activated remote inference (at your Settings page), your key is automatically stored. If you are using EDSL locally, create a file named .env in your EDSL working directory and store your key in it using the following format:

EXPECTED_PARROT_API_KEY = 'your_key_here'

3. Post objects to Coop

Post objects to the Coop using the edsl.coop module and methods (see examples below). You can set the visibility status of an object when you post it to the Coop or update it later. There are 3 status options:

  • public: Visible to everyone

  • private: Visible to logged in users that you have granted access

  • unlisted: Visible to anyone with the link but not listed in search results (default)

See details on methods for uploading, downloading, updating and deleting content at Coop.

4. Explore content

After you have posted content, navigate to your Content page to view and interact with it:

View your content at the Coop

You can access public content at the Explore tab, and copy code and examples to modify or rerun at your workspace.

Methods

When remote inference is activated the results of your surveys are automatically added to your Content page. You can modify them from your workspace or at the Coop app.

You can also post, update, download and delete any objects at the Coop using the edsl.coop module and methods (see examples below).

Uploading

There are 2 methods for uploading/posting an object from your workspace to Coop:

  1. Call the push() method on the object directly.

  2. Call the create() method on a Coop client object and pass it the object.

You can optionally pass a description, a convenient alias for the Coop URL and a visibility status (public, private or unlisted (default)) when you create an object. These can be changed at any time.

Direct method

Here we post a question object by calling the push() method on it:

from edsl import QuestionFreeText

q = QuestionFreeText(
  question_name = "example",
  question_text = "How are you today?"
)

q.push(
  description="This is an example question", # optional
  alias = "my-example-question", # optional
  visibility="public" # optional
)

We can see the description, alias and visibility status that we specified in the information that is returned:

{'description': 'This is an example question',
'object_type': 'question',
'url': 'https://www.expectedparrot.com/content/1706e6f9-2675-4433-8b0a-080654a5cd08',
'alias_url': 'https://www.expectedparrot.com/content/RobinHorton/my-example-question',
'uuid': '1706e6f9-2675-4433-8b0a-080654a5cd08',
'version': '0.1.47.dev1',
'visibility': 'public'}

Using a Coop client

Here we post the same question by passing it to the create() method of a Coop client object:

from edsl import Coop, QuestionFreeText

q = QuestionFreeText(
  question_name = "example",
  question_text = "How are you today?"
)
c = Coop()
c.create(q)

Here we include a description and visibility status:

from edsl import Coop, QuestionFreeText

q = QuestionFreeText(
  question_name = "example",
  question_text = "How are you today?"
)
c = Coop()
c.create(object=q, description="This is an example question", alias = "another-example-question", visibility="public")

This will return the same information about the object as the direct method shown above (with a unique uuid and URL for viewing the object at the Coop web app).

Updating

There are 3 methods for updating/editing an object to the Coop:

  1. Edit the object at the Coop web app.

  2. Call the patch() method on the object directly.

  3. Call the patch() method on a Coop client object.

For each patch() method, pass the alias_url or the uuid of the object and the parameter(s) that you want to update: description, visibility, alias and/or value.

  • The description parameter is used to update the description of an object, such as a question or survey.

  • The visibility parameter is used to update the visibility of an object: public, private or unlisted.

  • The value parameter is used to update the content of an object, such as the text of a question or the code in a notebook.

At the Coop web app

You can manually update the description or visibility of an object at the Coop web app. Navigate to the Explore page and open the page view for an object. You can select options to change the visibility of the object (public, private or unlisted) or to edit the description:

Page view of an object at Coop

Direct method

Here we update the description and visibility of the question we created and uploaded in the examples above by calling the patch() method on it:

q.patch("https://www.expectedparrot.com/content/RobinHorton/my-example-question",
        description="This is an updated question",
        visibility="unlisted")

This will return a status message:

{'status': 'success'}

Here we change the question itself by modifying the value parameter:

from edsl import QuestionMultipleChoice

new_q = QuestionMultipleChoice(
  question_name = "example",
  question_text = "How are you today?",
  question_options = ["Good", "Bad", "OK"]
)
q.patch("https://www.expectedparrot.com/content/RobinHorton/my-example-question",
        value=new_q)

Using a Coop client

Here we do the same using a Coop client object:

from edsl import Coop

c = Coop()
c.patch("https://www.expectedparrot.com/content/1706e6f9-2675-4433-8b0a-080654a5cd08",
        description="This is an updated question",
        visibility="public")

This will return the same status message as above.

Replicating / Downloading

There are a variety of methods for replicating or downloading an object at the Coop:

  1. Selecting options to download or copy code at the Coop web app

  2. Calling the pull() method on the class of the object

  3. Calling the get() method on a Coop client object

Copy code at the Coop web app

The Coop web app provides copyable code for downloading or reconstructing an object that has been posted:

  • Navigate to the Explore page and select an object

  • Go to the object’s page

  • Select the option to Download the object

OR

  • Select the option to Pull the object using its uuid or Raw to get the code for constructing the object:

Get code for pulling or reconstructing an object on the Coop

Get code for reconstructing an object on the Coop

Use this code in your workspace to download the object locally or to reconstruct it.

Class method

Here we download the question posted above by calling the pull() method on the object class (Question) and passing the uuid of the object:

from edsl import Question

q = Question.pull("1706e6f9-2675-4433-8b0a-080654a5cd08")
q

This will return the object (the multiple choice question question that replaced the free text question):

key

value

question_name

example

question_text

How are you today?

question_options:0

Good

question_options:1

Bad

question_options:2

OK

question_type

multiple_choice

Using a Coop client

Here we download the question by calling the get() method on a Coop client object:

from edsl import Coop

c = Coop()
q = c.get("1706e6f9-2675-4433-8b0a-080654a5cd08")
q

This will return the same object as above.

Deleting

There are 3 methods for deleting an object from the Coop:

  1. Selecting options to delete at the Coop web app

  2. Calling the delete() method on the class of the object

  3. Calling the delete() method on a Coop client object

At the Coop web app

You can manually delete objects at the Coop web app:

  • Navigate to Explore and open an object’s page view (see image above for Uploading content)

  • Select the option to delete the object:

Delete an object on the Coop

Directly

Here we delete a question object by calling the delete() method on the class of the object (Question) and passing the uuid of the object:

from edsl import Question

Question.delete("1234abcd-abcd-1234-abcd-1234abcd1234") # mock uuid

This will return a status message:

{'status': 'success'}

Using a Coop client

Here we delete a question by calling the delete() method on a Coop client object, passing the uuid of the object:

from edsl import Coop

c = Coop()
c.delete(uuid="1234abcd-abcd-1234-abcd-1234abcd1234") # mock uuid

This will return the same status message as above (so long as the object was not already deleted).

Feature requests

If you have a feature request for the Coop, please let us know! There are several ways to do this:

The coop module provides connectivity with Expected Parrot’s cloud services.

This module enables EDSL to interact with cloud-based resources for enhanced functionality: 1. Remote storage and sharing of EDSL objects (surveys, agents, models, results, etc.) 2. Remote inference execution for running jobs in the cloud 3. Caching of interview results for improved performance and cost savings 4. API key management and authentication 5. Price and model availability information 6. Plugin registry and discovery

The primary interface is the Coop class, which serves as a client for the Expected Parrot API. Most users will only need to interact with the Coop class directly.

Examples:

```python from edsl.coop import Coop coop = Coop() # Uses API key from environment or stored location survey = my_survey.push() # Uploads survey to Expected Parrot job_info = coop.remote_inference_create(my_job) # Creates remote job

# Working with plugins from edsl.coop import get_available_plugins plugins = get_available_plugins() plugin_names = [p.name for p in plugins] ```

class edsl.coop.Coop(api_key: str | None = None, url: str | None = None)[source]

Bases: CoopFunctionsMixin

Client for the Expected Parrot API that provides cloud-based functionality for EDSL.

The Coop class is the main interface for interacting with Expected Parrot’s cloud services. It enables:

  1. Storing and retrieving EDSL objects (surveys, agents, models, results, etc.)

  2. Running inference jobs remotely for better performance and scalability

  3. Retrieving and caching interview results

  4. Managing API keys and authentication

  5. Accessing model availability and pricing information

The client handles authentication, serialization/deserialization of EDSL objects, and communication with the Expected Parrot API endpoints. It also provides methods for tracking job status and managing results.

When initialized without parameters, Coop will attempt to use an API key from: 1. The EXPECTED_PARROT_API_KEY environment variable 2. A stored key in the user’s config directory 3. Interactive login if needed

Attributes:

api_key (str): The API key used for authentication url (str): The base URL for the Expected Parrot API api_url (str): The URL for API endpoints (derived from base URL)

__init__(api_key: str | None = None, url: str | None = None) → None[source]

Initialize the Expected Parrot API client.

This constructor sets up the connection to Expected Parrot’s cloud services. If not provided explicitly, it will attempt to obtain an API key from environment variables or from a stored location in the user’s config directory.

Parameters:
api_key (str, optional): API key for authentication with Expected Parrot.

If not provided, will attempt to obtain from environment or stored location.

url (str, optional): Base URL for the Expected Parrot service.

If not provided, uses the default from configuration.

Notes:

  • The API key is stored in the EXPECTED_PARROT_API_KEY environment variable or in a platform-specific config directory

  • The URL is determined based on whether it’s a production, staging, or development environment

  • The api_url for actual API endpoints is derived from the base URL

Example:
>>> coop = Coop()  # Uses API key from environment or stored location
>>> coop = Coop(api_key="your-api-key")  # Explicitly provide API key
create(object: Agent | AgentList | Cache | LanguageModel | ModelList | Notebook | Type[QuestionBase] | Results | Scenario | ScenarioList | Survey, description: str | None = None, alias: str | None = None, visibility: Literal['private', 'public', 'unlisted'] | None = 'unlisted') → dict[source]

Store an EDSL object in the Expected Parrot cloud service.

This method uploads an EDSL object (like a Survey, Agent, or Results) to the Expected Parrot cloud service for storage, sharing, or further processing.

Parameters:

object (EDSLObject): The EDSL object to store (Survey, Agent, Results, etc.) description (str, optional): A human-readable description of the object alias (str, optional): A custom alias for easier reference later visibility (VisibilityType, optional): Access level for the object. One of:

  • “private”: Only accessible by the owner

  • “public”: Accessible by anyone

  • “unlisted”: Accessible with the link, but not listed publicly

Returns:
dict: Information about the created object including:

  • url: The URL to access the object

  • alias_url: The URL with the custom alias (if provided)

  • uuid: The unique identifier for the object

  • visibility: The visibility setting

  • version: The EDSL version used to create the object

Raises:

CoopServerResponseError: If there’s an error communicating with the server

Example:
>>> survey = Survey(questions=[QuestionFreeText(question_name="name")])
>>> result = coop.create(survey, description="Basic survey", visibility="public")
>>> print(result["url"])  # URL to access the survey
create_project(survey: Survey, project_name: str = 'Project', survey_description: str | None = None, survey_alias: str | None = None, survey_visibility: Literal['private', 'public', 'unlisted'] | None = 'unlisted')[source]

Create a survey object on Coop, then create a project from the survey.

delete(url_or_uuid: str | UUID) → dict[source]

Delete an object from the server.

Parameters:

url_or_uuid – The UUID or URL of the object. URLs can be in the form content/uuid or content/username/alias.

property edsl_settings: dict[source]

Retrieve and return the EDSL settings stored on Coop. If no response is received within 5 seconds, return an empty dict.

fetch_models() → ServiceToModelsMapping[source]

Fetch information about available language models from Expected Parrot.

This method retrieves the current list of available language models grouped by service provider (e.g., OpenAI, Anthropic, etc.). This information is useful for programmatically selecting models based on availability and for ensuring that jobs only use supported models.

Returns:
ServiceToModelsMapping: A mapping of service providers to their available models.

Example structure: {

“openai”: [“gpt-4”, “gpt-3.5-turbo”, …], “anthropic”: [“claude-3-opus”, “claude-3-sonnet”, …], …

}

Raises:

CoopServerResponseError: If there’s an error communicating with the server

Notes:

  • The availability of models may change over time

  • Not all models may be accessible with your current API keys

  • Use this method to check for model availability before creating jobs

  • Models may have different capabilities (text-only, multimodal, etc.)

Example:
>>> models = coop.fetch_models()
>>> if "gpt-4" in models.get("openai", []):
...     print("GPT-4 is available")
>>> available_services = list(models.keys())
>>> print(f"Available services: {available_services}")
fetch_prices() → dict[source]

Fetch the current pricing information for language models.

This method retrieves the latest pricing information for all supported language models from the Expected Parrot API. The pricing data is used to estimate costs for jobs and to optimize model selection based on budget constraints.

Returns:
dict: A dictionary mapping (service, model) tuples to pricing information.

Each entry contains token pricing for input and output tokens. Example structure: {

(‘openai’, ‘gpt-4’): {

‘input’: {‘usd_per_1M_tokens’: 30.0, …}, ‘output’: {‘usd_per_1M_tokens’: 60.0, …}

}

}

Raises:

ValueError: If the EDSL_FETCH_TOKEN_PRICES configuration setting is invalid

Notes:

  • Returns an empty dict if EDSL_FETCH_TOKEN_PRICES is set to “False”

  • The pricing data is cached to minimize API calls

  • Pricing may vary based on the model, provider, and token type (input/output)

  • All prices are in USD per million tokens

Example:
>>> prices = coop.fetch_prices()
>>> gpt4_price = prices.get(('openai', 'gpt-4'), {})
>>> print(f"GPT-4 input price: ${gpt4_price.get('input', {}).get('usd_per_1M_tokens')}")
fetch_rate_limit_config_vars() → dict[source]

Fetch a dict of rate limit config vars from Coop.

The dict keys are RPM and TPM variables like EDSL_SERVICE_RPM_OPENAI.

fetch_working_models() → list[dict][source]

Fetch a list of working models from Coop.

Example output:

[
{

“service”: “openai”, “model”: “gpt-4o”, “works_with_text”: True, “works_with_images”: True, “usd_per_1M_input_tokens”: 2.5, “usd_per_1M_output_tokens”: 10.0,

}

]

get(url_or_uuid: str | UUID, expected_object_type: Literal['agent', 'agent_list', 'cache', 'model', 'model_list', 'notebook', 'question', 'results', 'scenario', 'scenario_list', 'survey'] | None = None) → Agent | AgentList | Cache | LanguageModel | ModelList | Notebook | Type[QuestionBase] | Results | Scenario | ScenarioList | Survey[source]

Retrieve an EDSL object from the Expected Parrot cloud service.

This method downloads and deserializes an EDSL object from the cloud service using either its UUID, URL, or username/alias combination.

Parameters:
url_or_uuid (Union[str, UUID]): Identifier for the object to retrieve.

Can be one of: - UUID string (e.g., “123e4567-e89b-12d3-a456-426614174000”) - Full URL (e.g., “https://expectedparrot.com/content/123e4567…”) - Alias URL (e.g., “https://expectedparrot.com/content/username/my-survey”)

expected_object_type (ObjectType, optional): If provided, validates that the

retrieved object is of the expected type (e.g., “survey”, “agent”)

Returns:

EDSLObject: The retrieved object as its original EDSL class instance (e.g., Survey, Agent, Results)

Raises:

CoopNoUUIDError: If no UUID or URL is provided CoopInvalidURLError: If the URL format is invalid CoopServerResponseError: If the server returns an error (e.g., not found,

unauthorized access)

Exception: If the retrieved object doesn’t match the expected type

Notes:

  • If the object’s visibility is set to “private”, you must be the owner to access it

  • For objects stored with an alias, you can use either the UUID or the alias URL

Example:
>>> survey = coop.get("123e4567-e89b-12d3-a456-426614174000")
>>> survey = coop.get("https://expectedparrot.com/content/username/my-survey")
>>> survey = coop.get(url, expected_object_type="survey")  # Validates the type
get_all(object_type: Literal['agent', 'agent_list', 'cache', 'model', 'model_list', 'notebook', 'question', 'results', 'scenario', 'scenario_list', 'survey']) → list[dict[str, Any]][source]

Retrieve all objects of a certain type associated with the user.

get_progress_bar_url()[source]
get_running_jobs() → list[str][source]

Get a list of currently running job IDs.

Returns:

list[str]: List of running job UUIDs

property headers: dict[source]

Return the headers for the request.

legacy_remote_cache_clear() → dict[source]

Clear all remote cache entries.

>>> entries = [CacheEntry.example(randomize=True) for _ in range(10)]
>>> coop.legacy_remote_cache_create_many(cache_entries=entries)
>>> coop.legacy_remote_cache_clear()
{'status': 'success', 'deleted_entry_count': 10}
legacy_remote_cache_clear_log() → dict[source]

Clear all remote cache log entries.

>>> coop.legacy_remote_cache_clear_log()
{'status': 'success'}
legacy_remote_cache_create_log(response: Response, description: str, cache_entry_count: int) → dict | None[source]

If a remote cache action has been completed successfully, log the action.

legacy_remote_cache_get(exclude_keys: list[str] | None = None, select_keys: list[str] | None = None) → list[CacheEntry][source]

Get all remote cache entries.

Parameters:

  • select_keys (optional) – Only return CacheEntry objects with these keys.

  • exclude_keys (optional) – Exclude CacheEntry objects with these keys.

>>> coop.legacy_remote_cache_get()
[CacheEntry(...), CacheEntry(...), ...]
legacy_remote_cache_get_diff(client_cacheentry_keys: list[str]) → dict[source]

Get the difference between local and remote cache entries for a user.

login()[source]

Starts the EDSL auth token login flow.

patch(url_or_uuid: str | UUID, description: str | None = None, alias: str | None = None, value: Agent | AgentList | Cache | LanguageModel | ModelList | Notebook | Type[QuestionBase] | Results | Scenario | ScenarioList | Survey | None = None, visibility: Literal['private', 'public', 'unlisted'] | None = None) → dict[source]

Change the attributes of an uploaded object

Parameters:

  • url_or_uuid – The UUID or URL of the object. URLs can be in the form content/uuid or content/username/alias.

  • description – Optional new description

  • alias – Optional new alias

  • value – Optional new object value

  • visibility – Optional new visibility setting

async remote_async_execute_model_call(model_dict: dict, user_prompt: str, system_prompt: str) → dict[source]
remote_cache_get(job_uuid: str | UUID | None = None) → list[CacheEntry][source]

Get all remote cache entries.

Parameters:

select_keys (optional) – Only return CacheEntry objects with these keys.

>>> coop.remote_cache_get(job_uuid="...")
[CacheEntry(...), CacheEntry(...), ...]
remote_cache_get_by_key(select_keys: list[str] | None = None) → list[CacheEntry][source]

Get all remote cache entries.

Parameters:

select_keys (optional) – Only return CacheEntry objects with these keys.

>>> coop.remote_cache_get_by_key(selected_keys=["..."])
[CacheEntry(...), CacheEntry(...), ...]
remote_inference_cost(input: Jobs | Survey, iterations: int = 1) → int[source]

Get the cost of a remote inference job.

Parameters:

input – The EDSL job to send to the server.

>>> job = Jobs.example()
>>> coop.remote_inference_cost(input=job)
{'credits': 0.77, 'usd': 0.0076950000000000005}
remote_inference_create(job: Jobs, description: str | None = None, status: Literal['queued', 'running', 'completed', 'failed'] = 'queued', visibility: Literal['private', 'public', 'unlisted'] | None = 'unlisted', initial_results_visibility: Literal['private', 'public', 'unlisted'] | None = 'unlisted', iterations: int | None = 1, fresh: bool | None = False) → RemoteInferenceCreationInfo[source]

Create a remote inference job for execution in the Expected Parrot cloud.

This method sends a job to be executed in the cloud, which can be more efficient for large jobs or when you want to run jobs in the background. The job execution is handled by Expected Parrot’s infrastructure, and you can check the status and retrieve results later.

Parameters:

job (Jobs): The EDSL job to run in the cloud description (str, optional): A human-readable description of the job status (RemoteJobStatus): Initial status, should be “queued” for normal use

Possible values: “queued”, “running”, “completed”, “failed”

visibility (VisibilityType): Access level for the job information. One of:

  • “private”: Only accessible by the owner

  • “public”: Accessible by anyone

  • “unlisted”: Accessible with the link, but not listed publicly

initial_results_visibility (VisibilityType): Access level for the job results iterations (int): Number of times to run each interview (default: 1) fresh (bool): If True, ignore existing cache entries and generate new results

Returns:
RemoteInferenceCreationInfo: Information about the created job including:

  • uuid: The unique identifier for the job

  • description: The job description

  • status: Current status of the job

  • iterations: Number of iterations for each interview

  • visibility: Access level for the job

  • version: EDSL version used to create the job

Raises:

CoopServerResponseError: If there’s an error communicating with the server

Notes:

  • Remote jobs run asynchronously and may take time to complete

  • Use remote_inference_get() with the returned UUID to check status

  • Credits are consumed based on the complexity of the job

Example:
>>> from edsl.jobs import Jobs
>>> job = Jobs.example()
>>> job_info = coop.remote_inference_create(job=job, description="My job")
>>> print(f"Job created with UUID: {job_info['uuid']}")
remote_inference_get(job_uuid: str | None = None, results_uuid: str | None = None) → RemoteInferenceResponse[source]

Get the status and details of a remote inference job.

This method retrieves the current status and information about a remote job, including links to results if the job has completed successfully.

Parameters:

job_uuid (str, optional): The UUID of the remote job to check results_uuid (str, optional): The UUID of the results associated with the job

(can be used if you only have the results UUID)

Returns:
RemoteInferenceResponse: Information about the job including:

  • job_uuid: The unique identifier for the job

  • results_uuid: The UUID of the results (if job is completed)

  • results_url: URL to access the results (if available)

  • latest_error_report_uuid: UUID of error report (if job failed)

  • latest_error_report_url: URL to access error details (if available)

  • status: Current status (“queued”, “running”, “completed”, “failed”)

  • reason: Reason for failure (if applicable)

  • credits_consumed: Credits used for the job execution

  • version: EDSL version used for the job

Raises:

ValueError: If neither job_uuid nor results_uuid is provided CoopServerResponseError: If there’s an error communicating with the server

Notes:

  • Either job_uuid or results_uuid must be provided

  • If both are provided, job_uuid takes precedence

  • For completed jobs, you can use the results_url to view or download results

  • For failed jobs, check the latest_error_report_url for debugging information

Example:
>>> job_status = coop.remote_inference_get("9f8484ee-b407-40e4-9652-4133a7236c9c")
>>> print(f"Job status: {job_status['status']}")
>>> if job_status['status'] == 'completed':
...     print(f"Results available at: {job_status['results_url']}")
web(survey: dict, platform: Literal['google_forms', 'lime_survey', 'survey_monkey'] = 'lime_survey', email=None)[source]
exception edsl.coop.CoopServerResponseError(message: str, *, show_docs: bool = True, log_level: str = 'error', silent: bool = False)[source]

Bases: CoopErrors

Exception raised when the server returns an error response.

This exception is raised when the Expected Parrot API returns an error response, such as authentication failures, rate limits, or server errors. The exception message typically includes the error details from the server.

To fix this error: 1. Check the exception message for specific error details from the server 2. For authentication errors (401), verify your API key is correct and not expired 3. For rate limit errors (429), reduce the frequency of your requests 4. For server errors (500+), the issue may be temporary - wait and try again 5. Check your network connection if you’re getting connection timeout errors

Example:

`python coop = Coop(api_key="invalid-key") coop.get("valid-uuid")  # Raises CoopServerResponseError with 401 Unauthorized `

relevant_doc = 'https://docs.expectedparrot.com/en/latest/api_keys.html'[source]
class edsl.coop.ObjectRegistry[source]

Bases: object

Registry that maps between EDSL class types and their cloud storage object types.

This utility class maintains a bidirectional mapping between EDSL Python classes (like Survey, Agent, Results) and their corresponding object type identifiers used in the cloud storage system. It enables the proper serialization, deserialization, and type checking for objects stored in Expected Parrot’s cloud services.

The registry is used by the Coop client to: 1. Determine the correct object type when uploading EDSL objects 2. Instantiate the correct class when downloading objects 3. Validate that retrieved objects match expected types

Attributes:

objects (list): List of mappings between object types and EDSL classes object_type_to_edsl_class (dict): Maps object type strings to EDSL classes edsl_class_to_object_type (dict): Maps EDSL class names to object type strings

edsl_class_to_object_type = {'Agent': 'agent', 'AgentList': 'agent_list', 'Cache': 'cache', 'LanguageModel': 'model', 'ModelList': 'model_list', 'Notebook': 'notebook', 'QuestionBase': 'question', 'Results': 'results', 'Scenario': 'scenario', 'ScenarioList': 'scenario_list', 'Survey': 'survey'}[source]
classmethod get_edsl_class_by_object_type(object_type: Literal['agent', 'agent_list', 'cache', 'model', 'model_list', 'notebook', 'question', 'results', 'scenario', 'scenario_list', 'survey']) → Agent | AgentList | Cache | LanguageModel | ModelList | Notebook | Type[QuestionBase] | Results | Scenario | ScenarioList | Survey[source]

Get the EDSL class for a given object type identifier.

This method returns the appropriate EDSL class for a given object type string, which is needed when retrieving objects from the cloud.

Parameters:

object_type (ObjectType): The object type string (e.g., “survey”, “agent”)

Returns:

EDSLObject: The corresponding EDSL class

Raises:

ValueError: If no mapping exists for the provided object type

classmethod get_object_type_by_edsl_class(edsl_object: Agent | AgentList | Cache | LanguageModel | ModelList | Notebook | Type[QuestionBase] | Results | Scenario | ScenarioList | Survey) → Literal['agent', 'agent_list', 'cache', 'model', 'model_list', 'notebook', 'question', 'results', 'scenario', 'scenario_list', 'survey'][source]

Get the object type identifier for an EDSL class or instance.

This method determines the appropriate object type string for a given EDSL class or instance, which is needed when storing the object in the cloud.

Parameters:

edsl_object (EDSLObject): An EDSL class (type) or instance

Returns:

ObjectType: The corresponding object type string (e.g., “survey”, “agent”)

Raises:

ValueError: If no mapping exists for the provided object

Notes:

  • Special handling for Question classes, which all map to “question”

  • Works with both class types and instances

classmethod get_registry(subclass_registry: dict | None = None, exclude_classes: list | None = None) → dict[source]

Get a filtered registry of EDSL classes.

This method returns a dictionary of EDSL classes, optionally excluding classes that are already registered elsewhere or explicitly excluded.

Parameters:
subclass_registry (dict, optional): Dictionary of classes to exclude

because they are already registered elsewhere

exclude_classes (list, optional): List of class names to explicitly exclude

Returns:

dict: Dictionary mapping class names to EDSL classes

Notes:

  • This method is useful for building registries of classes that can be serialized and stored in the cloud

  • It helps avoid duplicate registrations of classes

object_type_to_edsl_class = {'agent': <class 'edsl.agents.agent.Agent'>, 'agent_list': <class 'edsl.agents.agent_list.AgentList'>, 'cache': <class 'edsl.caching.cache.Cache'>, 'model': <class 'edsl.language_models.language_model.LanguageModel'>, 'model_list': <class 'edsl.language_models.model_list.ModelList'>, 'notebook': <class 'edsl.notebooks.notebook.Notebook'>, 'question': <class 'edsl.questions.question_base.QuestionBase'>, 'results': <class 'edsl.results.results.Results'>, 'scenario': <class 'edsl.scenarios.scenario.Scenario'>, 'scenario_list': <class 'edsl.scenarios.scenario_list.ScenarioList'>, 'survey': <class 'edsl.surveys.survey.Survey'>}[source]
objects = [{'edsl_class': <class 'edsl.agents.agent.Agent'>, 'object_type': 'agent'}, {'edsl_class': <class 'edsl.agents.agent_list.AgentList'>, 'object_type': 'agent_list'}, {'edsl_class': <class 'edsl.caching.cache.Cache'>, 'object_type': 'cache'}, {'edsl_class': <class 'edsl.language_models.language_model.LanguageModel'>, 'object_type': 'model'}, {'edsl_class': <class 'edsl.language_models.model_list.ModelList'>, 'object_type': 'model_list'}, {'edsl_class': <class 'edsl.notebooks.notebook.Notebook'>, 'object_type': 'notebook'}, {'edsl_class': <class 'edsl.questions.question_base.QuestionBase'>, 'object_type': 'question'}, {'edsl_class': <class 'edsl.results.results.Results'>, 'object_type': 'results'}, {'edsl_class': <class 'edsl.scenarios.scenario.Scenario'>, 'object_type': 'scenario'}, {'edsl_class': <class 'edsl.scenarios.scenario_list.ScenarioList'>, 'object_type': 'scenario_list'}, {'edsl_class': <class 'edsl.surveys.survey.Survey'>, 'object_type': 'survey'}][source]