TinyTroupe 🤠🤓🥸🧐

<p align="center"> <a href="https://trendshift.io/repositories/12206" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12206" alt="Yeah, we are totally fine for not getting to #1, no hard feelings at all." style="width: 250px; height: 55px;" width="250" height="55"/></a> </p>

LLM-powered multiagent persona simulation for imagination enhancement and business insights.

<p align="center"> <img src="./docs/tinytroupe_stage.png" alt="A tiny office with tiny people doing some tiny jobs."> </p>

[!TIP] 📄 New Paper Released! Check out our TinyTroupe paper (preprint) that describes the library and its use cases in detail. You can find the related experiments and complementary material in the publications/ folder.

TinyTroupe is an experimental Python library that allows the simulation of people with specific personalities, interests, and goals. These artificial agents - TinyPersons - can listen to us and one another, reply back, and go about their lives in simulated TinyWorld environments. This is achieved by leveraging the power of Large Language Models (LLMs), notably GPT-4, to generate realistic simulated behavior. This allows us to investigate a wide range of convincing interactions and consumer types, with highly customizable personas, under conditions of our choosing. The focus is thus on understanding human behavior and not on directly supporting it (like, say, AI assistants do) -- this results in, among other things, specialized mechanisms that make sense only in a simulation setting. Further, unlike other game-like LLM-based simulation approaches, TinyTroupe aims at enlightening productivity and business scenarios, thereby contributing to more successful projects and products. Here are some application ideas to enhance human imagination:

• Advertisement: TinyTroupe can evaluate digital ads (e.g., Bing Ads) offline with a simulated audience before spending money on them!
• Software Testing: TinyTroupe can provide test input to systems (e.g., search engines, chatbots or copilots) and then evaluate the results.
• Training and exploratory data: TinyTroupe can generate realistic synthetic data that can be later used to train models or be subject to opportunity analyses.
• Product and project management: TinyTroupe can read project or product proposals and give feedback from the perspective of specific personas (e.g., physicians, lawyers, and knowledge workers in general).
• Brainstorming: TinyTroupe can simulate focus groups and deliver great product feedback at a fraction of the cost!

In all of the above, and many others, we hope experimenters can gain insights about their domain of interest, and thus make better decisions.

We are releasing TinyTroupe at a relatively early stage, with considerable work still to be done, because we are looking for feedback and contributions to steer development in productive directions. We are particularly interested in finding new potential use cases, for instance in specific industries.

[!NOTE] 🚧 WORK IN PROGRESS: expect frequent changes. TinyTroupe is an ongoing research project, still under very significant development and requiring further tidying up. In particular, the API is still subject to frequent changes. Experimenting with API variations is essential to shape it correctly, but we are working to stabilize it and provide a more consistent and friendly experience over time. We appreciate your patience and feedback as we continue to improve the library.

[!CAUTION] ⚖️ Read the LEGAL DISCLAIMER. TinyTroupe is for research and simulation only. You are fully responsible for any use you make of the generated outputs. Various important additional legal considerations apply and constrain its use. Please read the full Legal Disclaimer section below before using TinyTroupe.

Contents

• 📰 Latest News
• 📚 Examples
• 🛠️ Pre-requisites
• 📥 Installation
• 🌟 Principles
• 🏗️ Project Structure
• 📖 Using the Library
• 🤝 Contributing
• 🙏 Acknowledgements
• 📜 Citing TinyTroupe
• ⚖️ Legal Disclaimer
• ™️ Trademarks

LATEST NEWS

<details open> <summary><b>[2026-03-28] Release 0.7.0: support for vision modality.</b></summary>

• Take a look one example Vision for Product, Diagnosis and Appreciation Feedback (image modality) notebook.
• LLM API caching now uses JSON instead of pickle.

</details> <details> <summary><b>[2026-02-01] Release 0.6.0 with new features and model updates</b></summary>

• Default model is now gpt-5-mini. Important: The GPT-5 model series uses different parameters than the former GPT-4* series, so you may need to adjust your config.ini settings accordingly. Legacy models (gpt-4.1-mini, gpt-4o-mini) are still supported.
• Introduces SimulationExperimentEmpiricalValidator to compare simulation results against real-world empirical data using statistical tests (t-test, KS-test). This is essential for validating that simulations match actual human behavior.
• Introduces AgentChatJupyterWidget for interactive conversations with agents directly in Jupyter notebooks.
• New cost tracking utilities at client, environment, and agent levels to monitor API expenses.
• Adds experimental/limited Ollama support for local models. See Ollama Support for details.
• New example notebooks demonstrating empirical validation against real survey data.

Note: GPT-5 model parameters differ from GPT-4, so please retest your important scenarios and adjust configurations accordingly.*

</details> <details> <summary><b>[2025-07-31] Release 0.5.2</b></summary>

Mostly just changes the default model, which is now set to GPT-4.1-mini. It seems to bring considerable quality improvements.

Note that GPT-4.1-mini can have significant differences in behavior w.r.t. to the previous default of GPT-4o-mini, so please make sure you retest your important scenarios using GPT-4.1-mini and adjust accordingly.

</details> <details> <summary><b>[2025-07-15] Release 0.5.1 with various improvements</b></summary>

• Released the first version of the TinyTroupe paper (as a preprint), which describes the library and its use cases in more detail. You can find the related experiments and complementary material in the publications/ folder.
• TinyPersons now include action correction mechanisms, allowing better adherence to persona specification, self-consistency and/or fluency (for details, refer to the paper we are releasing at the same time now).
• Substantial improvements to the TinyPersonFactory class, which now: uses a plan-based approach to generate new agents, allowing better sampling of larger populations; generate agents in parallel.
• TinyWorld now run agents in parallel within each simulation step, allowing faster simulations.
• InPlaceExperimentRunner class introduced to allow running controlled experiments (e.g., A/B testing) in a single file (by simply running it multiple times).
• Various standard Propositions were introduced to make it easier to run common verifications and monitoring of agent behavior (e.g., persona_adherence, hard_persona_adherence, self_consistency, fluency, etc.).
• Internal LLM usage is now better supported via the LLMChat class, and also the @llm decorator, which transform any standard Python function into an LLM-based one (i.e., by using the docstring as part of the prompt, and some other nuances). This is meant to make it easier to continue advancing TinyTroupe and also allow for some creative explorations of LLM tooling possibilities.
• Configuration mechanism has been refactored to allow, besides the static config.ini file, also the dynamic programmatic reconfiguration.
• Renamed Jupyter notebooks examples for better readability and consistency.
• Added many more tests.

Note: this will likely break some existing programs, as the API has changed in some places.

</details> <details> <summary><b>[2025-01-29] Release 0.4.0 with various improvements</b></summary>

• Personas have deeper specifications now, including personality traits, preferences, beliefs, and more. It is likely we'll further expand this in the future.
• TinyPersons can now be defined as JSON files as well, and loaded via the TinyPerson.load_specification(), for greater convenience. After loading the JSON file, you can still modify the agent programmatically. See the examples/agents/ folder for examples.
• Introduces the concept of fragments to allow the reuse of persona elements across different agents. See the examples/fragments/ folder for examples, and the notebook Political Compass (customizing agents with fragments) for a demonstration.
• Introduces LLM-based logical Propositions, to facilitate the monitoring of agent behavior.
• Introduces Interventions, to allow the specification of event-based modifications to the simulation.
• Submodules have their own folders now, to allow better organization and growth.

**Note: this will likely break some existing programs, as the API has changed in some p