Persistence: Save, Load, Push, Pull

All EDSL objects (including Agent and AgentList) inherit persistence methods from the Base class.

Local File Persistence (save/load)

Saving to Local Files

python

from edsl import Agent, AgentList

# Save a single agent (compressed by default)
agent = Agent(traits={"age": 30, "occupation": "doctor"})
agent.save("my_agent")  # Creates my_agent.json.gz

# Save uncompressed
agent.save("my_agent", compress=False)  # Creates my_agent.json

# Save an AgentList
agents = AgentList.from_source("people.csv")
agents.save("my_agents")  # Creates my_agents.json.gz

# Filename extensions are handled automatically
agent.save("my_agent.json.gz")  # Works the same
agent.save("my_agent.json")     # Works the same

Loading from Local Files

python

from edsl import Agent, AgentList

# Load a single agent
agent = Agent.load("my_agent")  # Auto-detects .json.gz or .json

# Load an AgentList
agents = AgentList.load("my_agents")

# Explicit extensions work too
agent = Agent.load("my_agent.json.gz")
agent = Agent.load("my_agent.json")

File Format Details

•Compressed (default): .json.gz - gzip-compressed JSON, smaller file size
•Uncompressed: .json - plain JSON, human-readable
•Both formats store the complete object state including traits, codebook, instructions, etc.
•The load() method auto-detects the format based on file extension

Cloud Persistence (push/pull)

EDSL objects can be stored on the Expected Parrot cloud platform for sharing and collaboration.

Pushing to the Cloud

python

from edsl import Agent, AgentList

agents = AgentList.from_source("survey_respondents.csv")

# Basic push (unlisted by default)
response = agents.push()
print(response)  # Contains UUID and URL

# Push with metadata
response = agents.push(
    description="Survey respondents from Q4 2024 study",
    alias="q4-respondents",           # Human-readable identifier
    visibility="private"               # "private", "unlisted", or "public"
)

# Update existing object (when alias already exists)
response = agents.push(
    alias="q4-respondents",
    force=True  # Patches existing object instead of creating new
)

Pulling from the Cloud

python

from edsl import AgentList

# Pull by UUID
agents = AgentList.pull("123e4567-e89b-12d3-a456-426614174000")

# Pull by full URL
agents = AgentList.pull("https://expectedparrot.com/content/123e4567...")

# Pull by alias URL
agents = AgentList.pull("https://expectedparrot.com/content/username/q4-respondents")

# Pull by shorthand alias (username/alias)
agents = AgentList.pull("username/q4-respondents")

Listing Cloud Objects

python

from edsl import AgentList

# List your AgentLists on the cloud
my_lists = AgentList.list()

# Filter by visibility
public_lists = AgentList.list(visibility="public")
private_lists = AgentList.list(visibility="private")

# Search by description
matching = AgentList.list(search_query="survey respondents")

# Pagination
page_2 = AgentList.list(page=2, page_size=20)

# Sort order (default: newest first)
oldest_first = AgentList.list(sort_ascending=True)

Managing Cloud Objects

python

from edsl import AgentList

# Update an existing object's metadata
AgentList.patch(
    "123e4567-e89b-12d3-a456-426614174000",
    description="Updated description",
    visibility="public"
)

# Update with new value (instance method)
agents = AgentList.from_source("updated_data.csv")
agents.patch(
    "123e4567-e89b-12d3-a456-426614174000",
    description="Replaced with new data"
)

# Delete from cloud
AgentList.delete("123e4567-e89b-12d3-a456-426614174000")

Visibility Levels

Level	Description
`"private"`	Only you can access
`"unlisted"`	Anyone with the URL/UUID can access (default)
`"public"`	Discoverable and accessible by everyone

Git-Based Versioning

AgentList supports git-like version control for tracking changes over time.

python

from edsl import AgentList

# Push to git-based storage
agents.git_push("my-agent-population")

# Clone from git-based storage
agents = AgentList.git_clone("username/my-agent-population")

Serialization to Dict/JSON/YAML

python

# To/from dictionary
d = agents.to_dict()
agents = AgentList.from_dict(d)

# To JSON string
json_str = agents.to_json()

# To/from YAML
yaml_str = agents.to_yaml()
agents = AgentList.from_yaml(yaml_str)

# Save YAML to file
agents.to_yaml(filename="agents.yaml")
agents = AgentList.from_yaml(filename="agents.yaml")

Quick Reference

Task	Single Agent	AgentList
Save locally	`agent.save("file")`	`agents.save("file")`
Load locally	`Agent.load("file")`	`AgentList.load("file")`
Push to cloud	`agent.push(alias="...")`	`agents.push(alias="...")`
Pull from cloud	`Agent.pull("uuid")`	`AgentList.pull("uuid")`
List on cloud	`Agent.list()`	`AgentList.list()`
Delete from cloud	`Agent.delete("uuid")`	`AgentList.delete("uuid")`
To dict	`agent.to_dict()`	`agents.to_dict()`
From dict	`Agent.from_dict(d)`	`AgentList.from_dict(d)`