Developer Quickstart

Overview

The Simile API provides a straightforward way to manage “agents,” which represent people or characters with unique traits and backgrounds. You can then pose questions to these agents and receive generated responses—whether categorical, numerical, or open-ended “chat” style.

The library also supports populations, i.e., groups of agents that allow you to organize, sample, or batch-process multiple agents at once. An agent can belong to multiple populations (for instance, a college student living in Philadelphia could be part of both a “college student” population and a “Philly residents” population).

Installation & Setup

Install the simile package via pip:

pip install simile
Copy

Then import and set your API key (first sign up, and then get your API key here):

import simile
 
# Set your API key
simile.api_key = "YOUR_API_KEY"
PythonCopy

General Workflow

In Simile, there are two core resource classes:

• Agent – a single entity with a defined personality, background, and optional data attachments
• Population – a group of agents that can be managed collectively

Common use cases include:

• Asking multiple agents (e.g., different demographic backgrounds) a question to see varied responses—like an A/B test or a quick poll.
• Holding a focused interview with a specific agent who represents certain traits, such as a Colorado-based rock climber.

Interacting with Agents

You can ask the agent different types of questions or prompts. The generate_response method currently supports:

• categorical: The agent picks from a list of provided options
• numerical: The agent returns a numeric value (within a specified range)
• chat: A freeform utterance in a dialogue format

Retrieving Agent Details

existing_details = simile.Agent.retrieve_details(new_agent_id)
print("Agent details:", existing_details)
PythonCopy

Categorical Example

agent_id = "AGENT_ID"
cat_question_payload = {
    "question": "What is your favorite color?",
    "options": ["Red", "Blue", "Green"]
}
cat_result = simile.Agent.generate_response(agent_id, "categorical", cat_question_payload)
print(cat_result)
PythonCopy

Numerical Example

num_question_payload = {
    "question": "How old are you?",
    "range": [0, 120]
}
num_result = simile.Agent.generate_response(agent_id, "numerical", num_question_payload)
print(num_result)
PythonCopy

Chat / Utterance Example

chat_payload = {
    "dialogue": [
        ["user", "Hello Agent, how are you?"],
        ["agent", "I'm doing well, thank you!"]
    ],
    "context": "Some prior conversation context or background..."
}
chat_result = simile.Agent.generate_response(agent_id, "chat", chat_payload)
print(chat_result)
PythonCopy

Managing Populations

Populations allow you to manage groups of agents.

Sample a Sub-Population

# Getting a random sample
subpop_result = simile.Population.get_sub_population(population_id=population_id, n=2)
print(subpop_result)
PythonCopy

The returned sub-population result a list of sampled agents. n has to be less than the number of agents in the population.

Error Handling

The simile.error module defines custom exceptions you may encounter:

• ApiKeyNotSetError – If you try to make a request without simile.api_key set
• AuthenticationError – If the server returns a 401 (invalid API key)
• RequestError – For other 4xx or 5xx HTTP errors, or network issues

try:
    agent_info = simile.Agent.retrieve_details("nonexistent_id")
except simile.error.RequestError as e:
    print("Request failed:", e)
PythonCopy

Putting It All Together

Here’s a quick outline showing how you might combine these methods in a script.

import simile
 
# Set your Simile API key
simile.api_key = "YOUR_API_KEY"
 
# Specify the population from which we want to sample
population_id = "YOUR_POPULATION_ID"
 
try:
    # Get a random sample of agents (e.g., 3) from your population
    subpop = simile.Population.get_sub_population(population_id, n=3)
 
    # For each agent in our sampled sub-population:
    for agent_info in subpop:
        agent_id = agent_info["agent_id"]  # or however the agent ID is accessed
 
        print(f"---\nAsking agent {agent_id} a categorical question...")
 
        # Define a categorical question payload
        cat_question_payload = {
            "question": "Do you prefer red, blue, or green?",
            "options": ["Red", "Blue", "Green"]
        }
 
        # Generate a response for the question
        cat_result = simile.Agent.generate_response(agent_id, "categorical", cat_question_payload)
 
        # Print out the agent’s response
        print(f"Agent {agent_id} answered: {cat_result}")
 
except simile.error.RequestError as e:
    print("Request failed:", e)
PythonCopy

With this approach, you can experiment with different question types (categorical, numerical, chat) and create or manage multiple agents/populations.