Java and JavaScript Clients

Create custom simulations or add generative agents to your own video games by using the clients.

Add the dependencies

Use maven to add jitpack to your repositories

pom.xml

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

Then you can add any commit version as a dependency

pom.xml

<dependencies>
    <dependency>
        <groupId>com.github.nickm980</groupId>
        <artifactId>smallville</artifactId>
        <version>2b663b0</version>
    </dependency>
</dependencies>

For a full example visit this pom.xml (opens in a new tab)

Get Started

Initialize a new connection

The client will attempt to recconect to the server on initialization, and will call the callback whenever the state is updated. The server will run on http://localhost:8080/ (opens in a new tab) by default

SmallvilleClient client = SmallvilleClient.create("http://localhost:8080", new AgentHandlerCallback() {
    public void handle(SimulationUpdateEvent event) {}
});

Create new locations

It's reccomended to create locations for interactable leaf objects. For example, create a location for Red House: John's Room: Chair, but not for Red House: Bedroom. Every simulation needs at least 1 location before creating agents, but it's reccomended to have more.

client.createLocation("Red House: Bathroom: Sink");

You can also set the initial state

client.createLocation("Red House: Kitchen: Stove",  "off");

Add a generative agent

Locations need to be created before adding agents

Initial memories should include characteristics, relationships, and occupations

Create the memories

List<String> memories = new ArrayList<String>();
memories.add("John is the son of Medina");

Add the agent

client.createAgent("John", memories, "Red House: Kitchen: Stove", "Cooking");

Update the state

Updating the state can take up to 5 minutes while reactions usually take 1-5 minutes. The agent handler callback function will be called when the state is finished updating.

client.updateState();

Adding observations

For the agents to react to their environment they need to have observations of the world. Reactions can take a long time so it's not reccomended to request reactions on reptitive events.

Reactable observations can cause agents to initiate conversation

Setting the last argument to true will make the agent possibly react to the observation.

client.addObservation("John", "desk is idle", true);

Interviewing agents

During interviews, agents assume they are being interviewed by a newscaster. This can be changed in the prompts configuration.

Agent interviews will not add the conversation to the agent's memory stream.

Setting the last argument to true will request a reaction from the agent. The agent will then choose if they should react and what that reaction should be.

client.ask("John", "How are you today?");

Example Projects

For more in depth example projects view the code of the example projects (opens in a new tab)

Dashboard Setup Memory Stream Database