TinyTroupe.md

TinyTroupe Documentation

Introduction

TinyTroupe is a Python framework designed for agent-based simulations that mimic human behavior, enriched with emotions, quirks, and personal histories. Utilizing principles from cognitive psychology, this framework is ideal for researchers, developers, and anyone interested in creating simulations of social interactions.

Why Use TinyTroupe?

• Rich Simulations: Enables detailed modeling of human-like behavior including cognitive and emotional aspects.
• Extensibility: Provides flexible modules for customizing to various specific use cases.
• Comprehensive: Manages complex aspects such as memory, cognitive abilities, and social interactions.

High-Level Overview

graph TD
    A[Simulation] -->|Manages| B[TinyWorld]
    B -->|Hosts| C[TinyPerson]
    C -->|Interacts via| D[Memory]
    C -->|Uses| E[Mental Faculties]
    C -->|Relates through| F[TinySocialNetwork]

Loading

• Simulation: Controls the progression of time and interactions.
• TinyWorld: The environment where agents interact.
• TinyPerson: The agents themselves.
• Memory: Stores personal and factual information.
• Mental Faculties: Abilities that determine behaviors.
• TinySocialNetwork: Manages relationships between agents.

Key Concepts with Examples

Agents (TinyPerson)

Agents are simulated individuals, each with unique characteristics, memories, and cognitive faculties, capable of interacting within their environment and with other agents.

Agent Interactions:

graph TD
    A[Agent A: TinyPerson] -- Relates To --> B[Agent B: TinyPerson]
    B --> C[Agent C: TinyPerson]
    A --> D[TinyWorld Environment]

Loading

Example:

from tinytroupe.agent import TinyPerson, EpisodicMemory, SemanticMemory

agent = TinyPerson(
    name="Alice",
    episodic_memory=EpisodicMemory(),
    semantic_memory=SemanticMemory(),
    mental_faculties=["RecallFaculty"]
)

agent.define_relationships({"Bob": "Friend", "Charlie": "Colleague"})
agent.define("age", 30)
agent.define("occupation", "Researcher")

agent.listen("Hi Alice, how are you?")
response = agent.act(return_actions=True)
print(response)

Environments (TinyWorld)

Environments provide the context and rules for agent interactions, essential for simulating specific scenarios like workplaces or social events.

Environment Interactions:

graph TD
    A[TinyWorld] -->|Hosts| B[Agent A]
    A -->|Hosts| C[Agent B]
    B -->|Actions Affect| A
    C -->|Actions Affect| A

Loading

Example:

from tinytroupe.environment import TinyWorld

world = TinyWorld(name="Office")
world.add_agent(agent)
world.add_agent(other_agent)

world.step()

Memory

Agents possess both episodic and semantic memory, enabling them to recall past experiences and utilize stored knowledge.

Memory Processes:

graph TD
    A[Agent] -->|Stores Experiences| B[Episodic Memory]
    A -->|Retrieves Knowledge| C[Semantic Memory]

Loading

Example:

agent.episodic_memory.store("Met Bob at the coffee shop.")
recent_memories = agent.episodic_memory.retrieve_recent()
print(recent_memories)

agent.semantic_memory.store("The Eiffel Tower is in Paris.")
facts = agent.semantic_memory.retrieve_relevant("Eiffel Tower")
print(facts)

Mental Faculties

Mental faculties are cognitive abilities that enable agents to process information, make decisions, and interact with their environment.

Cognitive Abilities:

graph TD
    A[Agent] -->|Uses| B[RecallFaculty]
    A -->|Uses| C[ToolUseFaculty]

Loading

Example:

from tinytroupe.agent import RecallFaculty

agent.add_mental_faculty(RecallFaculty(name="Memory Recall"))
response = agent.act(return_actions=True)
print(response)

Advanced Features

Social Networks (TinySocialNetwork)

A special type of environment that manages complex relationships between agents, enhancing the realism of social dynamics.

Social Network Dynamics:

graph TD
    A[Agent A] --Friend--> B[Agent B]
    B --Colleague--> C[Agent C]

Loading

Example:

from tinytroupe.environment import TinySocialNetwork

social_network = TinySocialNetwork(name="Office Network")
social_network.add_relation(agent, other_agent, name="Friend")

is_friend = social_network.is_in_relation_with(agent, other_agent, "Friend")
print(is_friend)

Integrating OpenAI APIs

Integrates OpenAI or Azure APIs for generating complex agent actions and realistic responses.

API Interaction Flow:

graph TD
    A[Agent] -->|Sends Prompt| B[OpenAI API]
    B -->|Returns Response| A

Loading

Example:

from tinytroupe.openai_utils import OpenAIClient

client = OpenAIClient(api_key="your-api-key")
response = client.call(
    system_template_name="agent_instructions",
    user_template_name="conversation",
    max_tokens=150
)
print(response)

Error Handling

Common errors and their solutions are outlined to ensure robust and stable simulations.

Error	Cause	Solution
InvalidRequestError	Invalid API call	Verify parameters and templates.
NonTerminalError	Retryable issue (e.g., timeout)	Implement retries or backoff strategies.

Glossary

• Agent (TinyPerson): Simulated individual with unique characteristics.
• Environment (TinyWorld): The simulated world where agents interact.
• Episodic Memory: Personal experiences stored by agents.
• Semantic Memory: Factual knowledge stored by agents.
• Mental Faculties: Cognitive abilities that influence agent behavior.