### Start Jupyter Notebook Server

Source: https://github.com/microsoft/tinytroupe/blob/main/README.md

Start a Jupyter Notebook server to access and run the examples provided in the repository. Navigate to the 'examples/' folder after starting.

```bash
jupyter notebook
```

--------------------------------

### Instantiate and Interact with Example Agent

Source: https://github.com/microsoft/tinytroupe/blob/main/README.md

Use pre-defined example builders to create a TinyPerson agent and interact with it. This is a quick way to get started with a pre-configured agent.

```python
from tinytroupe.examples import create_lisa_the_data_scientist

lisa = create_lisa_the_data_scientist() # instantiate a Lisa from the example builder
lisa.listen_and_act("Tell me about your life.")
```

--------------------------------

### begin

Source: https://github.com/microsoft/tinytroupe/blob/main/docs/api/tinytroupe/control.html

Marks the start of the simulation being controlled. Can configure caching and auto-checkpointing.

```APIDOC
## begin

### Description
Marks the start of the simulation being controlled. This method initializes the simulation state, clears previous entities, and optionally loads from a cache file.

### Method Signature
def begin(self, cache_path: str = None, auto_checkpoint: bool = False)

### Parameters
- **`cache_path`** (str): The path to the cache file. If not specified, defaults to the class's default cache path.
- **`auto_checkpoint`** (bool, optional): Whether to automatically checkpoint at the end of each transaction. Defaults to False.
```

--------------------------------

### Clone TinyTroupe Repository

Source: https://github.com/microsoft/tinytroupe/blob/main/README.md

Clone the TinyTroupe GitHub repository to your local machine. This is required for local installation and running examples.

```bash
git clone https://github.com/microsoft/tinytroupe
cd tinytroupe
```

--------------------------------

### Initialize and Start Logger

Source: https://github.com/microsoft/tinytroupe/blob/main/docs/api/tinytroupe/index.html

Reads the configuration file, prints version and datetime information, displays the configuration, and starts the logger based on the loaded configuration.

```python
# Create global instance of the configuration manager
config = utils.read_config_file()
utils.pretty_print_tinytroupe_version()
utils.pretty_print_datetime()
utils.pretty_print_config(config)
utils.start_logger(config)

config_manager = ConfigManager()
```

--------------------------------

### List Available Example Fragments

Source: https://github.com/microsoft/tinytroupe/blob/main/docs/api/tinytroupe/examples/loaders.html

Returns a list of all available example fragment names by scanning the './fragments' directory for files ending with '.fragment.json'.

```python
def list_example_fragments():
    """
    List the available example fragments.

    Returns:
        list: A list of the available example fragments.
    """
    return [f.replace('.fragment.json', '') for f in os.listdir(os.path.join(os.path.dirname(__file__), './fragments'))]
```

--------------------------------

### Simulation Log Output

Source: https://github.com/microsoft/tinytroupe/blob/main/publications/paper_artifacts_october-2025/Travel Product Market Research 2b.ipynb

Example log output from the tinytroupe simulation, indicating the start of a simulation step for a specific target audience.

```log
2025-10-03 10:34:14,542 - tinytroupe - INFO - [Target audience 1 (US)] Running world simulation step 1 of 1.

```

--------------------------------

### Loading Agent Example Specifications

Source: https://github.com/microsoft/tinytroupe/blob/main/docs/api/tinytroupe/factory/tiny_person_factory.html

This code demonstrates how to load agent specifications from JSON files. It's useful for initializing or referencing agent configurations stored externally.

```python
        # read example specs from files.
        example_1 = json.load(
            open(
                os.path.join(
                    os.path.dirname(__file__),
                    "../examples/agents/Friedrich_Wolf.agent.json",
                ),
                "r",
                encoding="utf-8",
                errors="replace",
            )
        )
        example_2 = json.load(
            open(
                os.path.join(
                    os.path.dirname(__file__),
                    "../examples/agents/Sophie_Lefevre.agent.json",
                ),
                "r",
                encoding="utf-8",
                errors="replace",
            )
        )
```

--------------------------------

### Python Error Handling Example

Source: https://github.com/microsoft/tinytroupe/blob/main/publications/paper_artifacts_june-2025/Brainstorming and Focus Group Quantitative Experimentation 2.3 - treatment run.ipynb

Demonstrates a TypeError that occurs when attempting to get the length of a NoneType object, likely due to an uninitialized or failed operation.

```python
TypeError: object of type 'NoneType' has no len()
```

--------------------------------

### Create and Populate a TinyWorld

Source: https://github.com/microsoft/tinytroupe/blob/main/examples/Political Compass (customizing agents with fragments).ipynb

Initializes a TinyWorld simulation with a list of agents and makes all agents accessible within the world. This is a setup step before starting interactions.

```python
world = TinyWorld("Chat Room", [oscar, friedrich, joseph, matias])
world.make_everyone_accessible()
```

--------------------------------

### Simulation.begin

Source: https://github.com/microsoft/tinytroupe/blob/main/docs/api/tinytroupe/control.html

Starts a new simulation. This is a fundamental operation to initiate the simulation environment.

```APIDOC
## Simulation.begin

### Description
Starts a new simulation.

### Method
`Simulation.begin()`

### Parameters
None

### Response
None

### Request Example
```python
simulation.begin()
```

### Response Example
None
```

--------------------------------

### Example Usage of CONSULT and LIST_DOCUMENTS

Source: https://github.com/microsoft/tinytroupe/blob/main/docs/api/tinytroupe/agent/mental_faculty.html

This example demonstrates the sequence of actions for consulting a document. First, list available documents, then consult a specific one, reflect on its content, and finally talk. This is useful when you need specific information from a known document.

```python
LIST_DOCUMENTS
<CONSULT some document name>
<THINK something about the retrieved document>
<TALK something>
DONE
```

--------------------------------

### Initial Conversational Prompt

Source: https://github.com/microsoft/tinytroupe/blob/main/publications/paper_artifacts_june-2025/Brainstorming and Focus Group Quantitative Experimentation 2.2 - treatment run.ipynb

The initial prompt delivered to the agents to start the discussion, guiding them to introduce themselves and present problems related to the theme of Discovery and Exploration.

```text
USER --> Clara White: [\n          >                  Hello everyone! Let's start by introducing ourselves, and mentioning\n          > problems we face in our daily personal                 and professional lives related to\n          > the following theme: Discovery and Exploration                                  Please:\n          > - present yourself and your background;                   - present some key personal\n          > problems related to the theme;                   - present some key problems related to\n          > the theme that you face in your work;                   - present some key problems\n          > related to the theme that you see in your industry as a whole.\n          > Don't discuss solutions yet, just the problems you face and see others facing.
```

--------------------------------

### Get Metric Summary

Source: https://github.com/microsoft/tinytroupe/blob/main/docs/api/tinytroupe/validation/simulation_validator.html

Retrieves a summary for a specified metric, including its name and result type. This method serves as a starting point for more detailed metric information.

```python
def get_metric_summary(self, metric_name: str) -> Dict[str, Any]:
            """Get a comprehensive summary of a metric including data type information."""
            summary = {
                "metric_name": metric_name,
                "result_type": self.result_types.get(metric_name, "unknown"),

```

--------------------------------

### Load Agent Specification from File

Source: https://github.com/microsoft/tinytroupe/blob/main/docs/api/tinytroupe/examples/agents.html

Load an agent's specification by its name from a predefined example file. This is a convenient way to initialize agents with complex configurations.

```python
def create_lila_the_linguist():
      return TinyPerson.load_specification(load_example_agent_specification("Lila"))
```

--------------------------------

### list_example_fragments

Source: https://github.com/microsoft/tinytroupe/blob/main/docs/api/tinytroupe/examples/loaders.html

Lists the names of all available example fragments.

```APIDOC
## list_example_fragments()

### Description
Lists the available example fragments.

### Returns
- `list`: A list of the available example fragments.
```