# microsoft/tinytroupe architecture

> Architecture diagram of the GitHub repository microsoft/tinytroupe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/tinytroupe
- Repository: https://github.com/microsoft/tinytroupe

## Overview

TinyTroupe is a Python library for LLM-powered multiagent persona simulation. Experimenters create or configure personas, place agents in simulated worlds, and observe interactions to investigate human behavior and business questions; outputs can then be extracted and simulations validated. The graph includes the documented experimentation, steering, enrichment, tools, and notebook capabilities. Evidence is limited to the supplied README and source index/excerpts; links for unsampled modules are included only where the index or README supports them.

Main entry points: [`tinytroupe/agent/tiny_person.py`](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/agent/tiny_person.py) (Simulated Person), [`tinytroupe/environment/tiny_world.py`](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/environment/tiny_world.py) (Simulation World), [`tinytroupe/clients/__init__.py`](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/clients/__init__.py) (Model Client Registry), [`tinytroupe/tools/tiny_tool.py`](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/tools/tiny_tool.py) (Agent Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Persona Simulation"]
  node_persona_factory["Persona Factory"]
  node_factory_core["Factory Core<br/>[tiny_factory.py]"]
  node_persona["Simulated Person<br/>[tiny_person.py]"]
  node_world["Simulation World<br/>[tiny_world.py]"]
  node_social_network["Social Network"]
  node_transactions["Simulation Control<br/>[control.py]"]
end

subgraph group_models["Models and Cognition"]
  node_action_generation["Action Generation"]
  node_memory["Agent Memory<br/>[memory.py]"]
  node_mental_faculty["Mental Faculties<br/>[mental_faculty.py]"]
  node_grounding["Web Grounding<br/>[grounding.py]"]
  node_llm_chat["LLM Chat<br/>[llm.py]"]
  node_client_registry["Model Client Registry<br/>[__init__.py]"]
  node_openai_client["OpenAI Client<br/>[openai_client.py]"]
  node_azure_client["Azure Client<br/>[azure_client.py]"]
  node_ollama_client["Ollama Client<br/>[ollama_client.py]"]
end

subgraph group_experiments["Experimentation and Analysis"]
  node_experiment_runner["Experiment Runner"]
  node_propositions["Propositions<br/>[proposition.py]"]
  node_statistical_tests["Statistical Tests"]
  node_simulation_validator["Empirical Validation"]
  node_results_extraction["Results Extraction"]
  node_normalizer["Result Normalization<br/>[normalizer.py]"]
  node_reporting["Results Reporting"]
  node_artifact_export["Artifact Export"]
  node_intervention["Interventions<br/>[intervention.py]"]
  node_story["Simulation Stories<br/>[tiny_story.py]"]
end

subgraph group_interfaces["Extensions and Interfaces"]
  node_enrichment["Persona Enrichment<br/>[tiny_enricher.py]"]
  node_styling["Persona Styling<br/>[tiny_styler.py]"]
  node_tools["Agent Tools<br/>[tiny_tool.py]"]
  node_calendar["Calendar Tool<br/>[tiny_calendar.py]"]
  node_word_processor["Word Processor"]
  node_jupyter_widget["Jupyter Interaction<br/>[jupyter_widgets.py]"]
end

node_experimenter(("Experimenter"))

node_experimenter -->|"creates personas"| node_persona_factory
node_experimenter -->|"configures simulation"| node_world
node_persona_factory -->|"generates agents"| node_persona
node_factory_core -->|"supports generation"| node_persona_factory
node_persona -->|"generates actions"| node_action_generation
node_persona -->|"uses memory"| node_memory
node_persona -->|"uses faculties"| node_mental_faculty
node_mental_faculty -->|"uses grounding"| node_grounding
node_action_generation -->|"requests generation"| node_llm_chat
node_llm_chat -->|"selects client"| node_client_registry
node_client_registry -->|"registers client"| node_openai_client
node_client_registry -->|"registers client"| node_azure_client
node_client_registry -->|"registers client"| node_ollama_client
node_world -->|"runs agents"| node_persona
node_world -->|"uses control"| node_transactions
node_world -.->|"supports social structure"| node_social_network
node_experimenter -->|"runs experiments"| node_experiment_runner
node_experiment_runner -->|"evaluates propositions"| node_propositions
node_simulation_validator -->|"uses tests"| node_statistical_tests
node_simulation_validator -.->|"validates simulation"| node_persona
node_experimenter -->|"extracts results"| node_results_extraction
node_results_extraction -.->|"normalizes results"| node_normalizer
node_experimenter -->|"reports findings"| node_reporting
node_experimenter -->|"exports artifacts"| node_artifact_export
node_experimenter -->|"steers simulation"| node_intervention
node_experimenter -.->|"defines scenarios"| node_story
node_experimenter -.->|"enriches personas"| node_enrichment
node_experimenter -.->|"styles personas"| node_styling
node_persona -.->|"uses tools"| node_tools
node_tools -.->|"includes tool"| node_calendar
node_tools -.->|"includes tool"| node_word_processor
node_experimenter -->|"interacts in notebook"| node_jupyter_widget

click node_persona_factory "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/factory/tiny_person_factory.py"
click node_factory_core "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/factory/tiny_factory.py"
click node_persona "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/agent/tiny_person.py"
click node_action_generation "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/agent/action_generator.py"
click node_memory "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/agent/memory.py"
click node_mental_faculty "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/agent/mental_faculty.py"
click node_grounding "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/agent/grounding.py"
click node_world "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/environment/tiny_world.py"
click node_social_network "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/environment/tiny_social_network.py"
click node_transactions "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/control.py"
click node_llm_chat "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/utils/llm.py"
click node_client_registry "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/clients/__init__.py"
click node_openai_client "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/clients/openai_client.py"
click node_azure_client "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/clients/azure_client.py"
click node_ollama_client "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/clients/ollama_client.py"
click node_experiment_runner "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/experimentation/in_place_experiment_runner.py"
click node_propositions "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/experimentation/proposition.py"
click node_statistical_tests "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/experimentation/statistical_tests.py"
click node_simulation_validator "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/validation/simulation_validator.py"
click node_results_extraction "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/extraction/results_extractor.py"
click node_normalizer "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/extraction/normalizer.py"
click node_reporting "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/extraction/results_reporter.py"
click node_artifact_export "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/extraction/artifact_exporter.py"
click node_intervention "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/steering/intervention.py"
click node_story "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/steering/tiny_story.py"
click node_enrichment "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/enrichment/tiny_enricher.py"
click node_styling "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/enrichment/tiny_styler.py"
click node_tools "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/tools/tiny_tool.py"
click node_calendar "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/tools/tiny_calendar.py"
click node_word_processor "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/tools/tiny_word_processor.py"
click node_jupyter_widget "https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/ui/jupyter_widgets.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_persona_factory,node_factory_core,node_persona,node_world,node_social_network,node_transactions toneBlue
class node_action_generation,node_memory,node_mental_faculty,node_grounding,node_llm_chat,node_client_registry,node_openai_client,node_azure_client,node_ollama_client toneAmber
class node_experiment_runner,node_propositions,node_statistical_tests,node_simulation_validator,node_results_extraction,node_normalizer,node_reporting,node_artifact_export,node_intervention,node_story toneMint
class node_enrichment,node_styling,node_tools,node_calendar,node_word_processor,node_jupyter_widget toneRose
class node_experimenter toneIndigo
```

## Components

### Persona Simulation

- [Persona Factory](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/factory/tiny_person_factory.py): `tinytroupe/factory/tiny_person_factory.py`
- [Factory Core](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/factory/tiny_factory.py): `tinytroupe/factory/tiny_factory.py`
- [Simulated Person](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/agent/tiny_person.py): `tinytroupe/agent/tiny_person.py`
- [Simulation World](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/environment/tiny_world.py): `tinytroupe/environment/tiny_world.py`
- [Social Network](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/environment/tiny_social_network.py): `tinytroupe/environment/tiny_social_network.py`
- [Simulation Control](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/control.py): `tinytroupe/control.py`

### Models and Cognition

- [Action Generation](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/agent/action_generator.py): `tinytroupe/agent/action_generator.py`
- [Agent Memory](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/agent/memory.py): `tinytroupe/agent/memory.py`
- [Mental Faculties](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/agent/mental_faculty.py): `tinytroupe/agent/mental_faculty.py`
- [Web Grounding](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/agent/grounding.py): `tinytroupe/agent/grounding.py`
- [LLM Chat](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/utils/llm.py): `tinytroupe/utils/llm.py`
- [Model Client Registry](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/clients/__init__.py): `tinytroupe/clients/__init__.py`
- [OpenAI Client](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/clients/openai_client.py): `tinytroupe/clients/openai_client.py`
- [Azure Client](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/clients/azure_client.py): `tinytroupe/clients/azure_client.py`
- [Ollama Client](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/clients/ollama_client.py): `tinytroupe/clients/ollama_client.py`

### Experimentation and Analysis

- [Experiment Runner](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/experimentation/in_place_experiment_runner.py): `tinytroupe/experimentation/in_place_experiment_runner.py`
- [Propositions](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/experimentation/proposition.py): `tinytroupe/experimentation/proposition.py`
- [Statistical Tests](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/experimentation/statistical_tests.py): `tinytroupe/experimentation/statistical_tests.py`
- [Empirical Validation](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/validation/simulation_validator.py): `tinytroupe/validation/simulation_validator.py`
- [Results Extraction](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/extraction/results_extractor.py): `tinytroupe/extraction/results_extractor.py`
- [Result Normalization](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/extraction/normalizer.py): `tinytroupe/extraction/normalizer.py`
- [Results Reporting](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/extraction/results_reporter.py): `tinytroupe/extraction/results_reporter.py`
- [Artifact Export](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/extraction/artifact_exporter.py): `tinytroupe/extraction/artifact_exporter.py`
- [Interventions](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/steering/intervention.py): `tinytroupe/steering/intervention.py`
- [Simulation Stories](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/steering/tiny_story.py): `tinytroupe/steering/tiny_story.py`

### Extensions and Interfaces

- [Persona Enrichment](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/enrichment/tiny_enricher.py): `tinytroupe/enrichment/tiny_enricher.py`
- [Persona Styling](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/enrichment/tiny_styler.py): `tinytroupe/enrichment/tiny_styler.py`
- [Agent Tools](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/tools/tiny_tool.py): `tinytroupe/tools/tiny_tool.py`
- [Calendar Tool](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/tools/tiny_calendar.py): `tinytroupe/tools/tiny_calendar.py`
- [Word Processor](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/tools/tiny_word_processor.py): `tinytroupe/tools/tiny_word_processor.py`
- [Jupyter Interaction](https://github.com/microsoft/tinytroupe/blob/main/tinytroupe/ui/jupyter_widgets.py): `tinytroupe/ui/jupyter_widgets.py`

### Other components

- **Experimenter**

## Connections

- Experimenter → Persona Factory: creates personas (evidence: `README.md`)
- Experimenter → Simulation World: configures simulation (evidence: `README.md`)
- Persona Factory → Simulated Person: generates agents (evidence: `tinytroupe/factory/tiny_person_factory.py`)
- Factory Core → Persona Factory: supports generation (evidence: `tinytroupe/factory/tiny_factory.py`)
- Simulated Person → Action Generation: generates actions (evidence: `tinytroupe/agent/tiny_person.py`)
- Simulated Person → Agent Memory: uses memory (evidence: `tinytroupe/agent/tiny_person.py`)
- Simulated Person → Mental Faculties: uses faculties (evidence: `tinytroupe/agent/tiny_person.py`)
- Mental Faculties → Web Grounding: uses grounding (evidence: `tinytroupe/agent/mental_faculty.py`)
- Action Generation → LLM Chat: requests generation (evidence: `tinytroupe/agent/action_generator.py`)
- LLM Chat → Model Client Registry: selects client (evidence: `tinytroupe/utils/llm.py`)
- Model Client Registry → OpenAI Client: registers client (evidence: `tinytroupe/clients/__init__.py`)
- Model Client Registry → Azure Client: registers client (evidence: `tinytroupe/clients/__init__.py`)
- Model Client Registry → Ollama Client: registers client (evidence: `tinytroupe/clients/__init__.py`)
- Simulation World → Simulated Person: runs agents (evidence: `tinytroupe/environment/tiny_world.py`)
- Simulation World → Simulation Control: uses control (evidence: `tinytroupe/environment/tiny_world.py`)
- Simulation World → Social Network: supports social structure
- Experimenter → Experiment Runner: runs experiments (evidence: `README.md`)
- Experiment Runner → Propositions: evaluates propositions
- Empirical Validation → Statistical Tests: uses tests (evidence: `tinytroupe/validation/simulation_validator.py`)
- Empirical Validation → Simulated Person: validates simulation
- Experimenter → Results Extraction: extracts results
- Results Extraction → Result Normalization: normalizes results
- Experimenter → Results Reporting: reports findings
- Experimenter → Artifact Export: exports artifacts
- Experimenter → Interventions: steers simulation (evidence: `tinytroupe/steering/intervention.py`)
- Experimenter → Simulation Stories: defines scenarios
- Experimenter → Persona Enrichment: enriches personas
- Experimenter → Persona Styling: styles personas
- Simulated Person → Agent Tools: uses tools
- Agent Tools → Calendar Tool: includes tool
- Agent Tools → Word Processor: includes tool
- Experimenter → Jupyter Interaction: interacts in notebook (evidence: `README.md`)
