FileStore examples

CSV example

Here we create an example CSV file, post it to Coop using FileStore, and then retrieve it and use it to construct a ScenarioList and an AgentList.

To create a CSV file (this step can be skipped and your own file replaced in the following steps):

data = [
    ['Age', 'City', 'Occupation'],
    [25, 'New York', 'Software Engineer'],
    [30, 'San Francisco', 'Teacher'],
    [35, 'Chicago', 'Doctor'],
    [28, 'Boston', 'Data Scientist'],
    [45, 'Seattle', 'Architect']
]

# Writing to CSV file
with open('data.csv', 'w') as file:
    for row in data:
        line = ','.join(str(item) for item in row)
        file.write(line + '\n')

Posting to Coop:

from edsl import FileStore

fs = FileStore("data.csv")
csv_info = fs.push(description = "My example CSV file", alias = "my-example-csv-file", visibility = "public")
csv_info # display the URL and Coop uuid of the stored file for retrieving it later

{'description': 'My example CSV file',
 'object_type': 'scenario',
 'url': 'https://www.expectedparrot.com/content/17c0e3d3-8d08-4ae0-bc7d-384a56a07e4e',
 'uuid': '17c0e3d3-8d08-4ae0-bc7d-384a56a07e4e',
 'version': '0.1.47.dev1',
 'visibility': 'public'}

Retrieving the file:

fs = FileStore.pull("https://www.expectedparrot.com/content/RobinHorton/my-example-csv-file")

This is equivalent:

fs = FileStore.pull(csv_info["uuid"])

Creating scenarios:

from edsl import ScenarioList

scenarios = ScenarioList.from_csv(fs.to_tempfile())
scenarios # display the scenarios

ScenarioList scenarios: 5; keys: ['City', 'Occupation', 'Age'];

	Age	City	Occupation
0	25	New York	Software Engineer
1	30	San Francisco	Teacher
2	35	Chicago	Doctor
3	28	Boston	Data Scientist
4	45	Seattle	Architect

Creating agents:

from edsl import AgentList

agents = AgentList.from_csv(fs.to_tempfile())
agents # display the agents

AgentList agents: 5;

	Age	City	Occupation
0	25	New York	Software Engineer
1	30	San Francisco	Teacher
2	35	Chicago	Doctor
3	28	Boston	Data Scientist
4	45	Seattle	Architect

These scenarios and agents can now be used with questions and surveys.

PNG example

Here we post an image file to Coop using FileStore, and then retrieve it and use it to construct a Scenario.

Note that we need to specify the scenario key for the file when we create it (whereas in CSV files the keys are taken from the text of the header row).

We also need to ensure that we have specified a vision model when running the survey (e.g., gpt-4o).

Posting a local file to Coop (replace with your own):

from edsl import FileStore

fs = FileStore("parrot_logo.png")
png_info = fs.push(description = "My example PNG file", alias = "my-example-png-file", visibility = "public")
png_info # display the URL and Coop uuid of the stored file for retrieving it later

{'description': 'My example PNG file',
 'object_type': 'scenario',
 'url': 'https://www.expectedparrot.com/content/b261660e-11a3-4bec-8864-0b6ec76dfbee',
 'uuid': 'b261660e-11a3-4bec-8864-0b6ec76dfbee',
 'version': '0.1.47.dev1',
 'visibility': 'public'}

Retrieving the file:

fs = FileStore.pull("https://www.expectedparrot.com/content/RobinHorton/my-example-png-file")

This is equivalent:

fs = FileStore.pull(png_info["uuid"])

Creating a scenario:

from edsl import Scenario

image_scenario = Scenario({"parrot_logo":fs}) # including a key for the scenario object

image_scenario.keys()

['parrot_logo']

To rename a scenario:

image_scenario = image_scenario.rename({"parrot_logo": "logo"}) # key = old name, value = new name
image_scenario.keys()

['logo']

Using an image scenario:

from edsl import QuestionFreeText, Model

model = Model("gpt-4o") # we need to use a vision model

q = QuestionFreeText(
    question_name = "test",
    question_text = "Describe this logo: {{ logo }}"
)

results = q.by(image_scenario).by(model).run()

▼ Job Status (2025-03-02 10:06:49)

Job UUID	e1ba2208-3400-41f3-a20c-e2e5f0455c99
Progress Bar URL	https://www.expectedparrot.com/home/remote-job-progress/e1ba2208-3400-41f3-a20c-e2e5f0455c99
Exceptions Report URL	None
Results UUID	bd2f016c-5747-43be-b7d9-da769d89cd48
Results URL	https://www.expectedparrot.com/content/bd2f016c-5747-43be-b7d9-da769d89cd48

✓Current Status: Job completed and Results stored on Coop: https://www.expectedparrot.com/content/bd2f016c-5747-43be-b7d9-da769d89cd48

results.select("model", "logo", "test")

	model.model	scenario.logo	answer.test
0	gpt-4o	FileStore: self.path	The logo features a large, stylized letter "E" in gray on the left. To the right of the "E" is an illustration of a parrot. The parrot is primarily green with an orange beak, a red chest, and blue lower body. It is enclosed in square brackets, also in gray.

PDF example

Here we save a PDF from the internet, then post it to Coop and retrieve it using FileStore, and then use it to construct a ScenarioList.

Note that the default scenario keys for a PDF are filename, page and text.

Selecting a file to use:

import requests

url = "https://arxiv.org/pdf/2404.11794"
response = requests.get(url)
with open("automated_social_scientist.pdf", "wb") as file:
    file.write(response.content)

Posting to Coop:

from edsl import FileStore

fs = FileStore("automated_social_scientist.pdf")
pdf_info = fs.push(description = "My example PDF file", alias = "my-example-pdf-file", visibility = "public")
pdf_info # display the URL and Coop uuid of the stored file for retrieving it later

{'description': 'My example PDF file',
 'object_type': 'scenario',
 'url': 'https://www.expectedparrot.com/content/e1770915-7e69-436d-b2ca-f0f92c6f56ba',
 'uuid': 'e1770915-7e69-436d-b2ca-f0f92c6f56ba',
 'version': '0.1.47.dev1',
 'visibility': 'public'}

Retriving the file:

fs = FileStore.pull("https://www.expectedparrot.com/content/RobinHorton/my-example-pdf-file")

This is equivalent:

fs = FileStore.pull(pdf_info["uuid"])

Creating scenarios:

from edsl import ScenarioList

scenarios = ScenarioList.from_pdf(fs.to_tempfile())

Inspecting the default keys:

scenarios.parameters

{'filename', 'page', 'text'}

Posting to Coop

Here we post this notebook to Coop, and show how to update it:

from edsl import Notebook

n = Notebook(path = "filestore_examples_new.ipynb")

info = n.push(description = "FileStore examples", alias = "my-example-filestore-notebook", visibility = "public")
info

{'description': 'FileStore examples',
 'object_type': 'notebook',
 'url': 'https://www.expectedparrot.com/content/02d57890-31c2-4bb8-ae7c-f646ac254d5a',
 'uuid': '02d57890-31c2-4bb8-ae7c-f646ac254d5a',
 'version': '0.1.47.dev1',
 'visibility': 'public'}

Use the patch() method to update an object at Coop:

n = Notebook(path = "filestore_examples_new.ipynb") # resave

n.patch("https://www.expectedparrot.com/content/RobinHorton/my-example-filestore-notebook", value = n)

{'status': 'success'}