How can we simulate nuanced human negotiation, irrational market sentiment, or adaptive trading strategies when our agents are bound by rigid if/else statements?

With this idea in mind, Riccardo Dal Cero and I developed Doxa as an open-source, Python-native simulation platform, designed from the ground up for modern researchers and developers. This project is based on the fundamental philosophy of separating the “what” from the “how” when describing the structure of your world, and how intelligent agents operate within it.

This is achieved through two key design principles:

Declarative scenarios with YAML allow you to define the entire simulation in a single, readable YAML file, instead of writing complex configuration scripts. This includes the agents, their initial resources, the markets they operate in, global rules, and even programmed global events like price shocks or resource shortages. This should make the scenarios incredibly easy to understand, manage, and share.

Doxa is designed to be AI-native, so it’s possible to integrate large language models from providers like Google (Gemini), OpenAI, or a local instance of Ollama to serve as the agents’ brains. By assigning an agent a personality, goals, and access to market data, sophisticated, nondeterministic decisions can be made that go far beyond simple rule-based logic.

We developed the system with FastAPI for the API layer and Pydantic for rigorous data validation, ensuring a robust and easily maintainable core. The modular architecture allows collaborators to easily create their own agent logic, market compensation mechanisms, or event types for specific research needs.

Therefore, reproducibility is key: simulation execution is completely determined by the scenario file and the Doxa version, making experiments scientifically valid and verifiable. Last but not least, Doxa is distributed as a command-line tool, a two-tier application, and a Colab platform, so it requires no complex configuration.

See it in action
Here’s a small snippet from a scenario defining a farmer-trader agent:

actors:
  - id: player_farmer
    provider: google
    model_name: gemini-1.5-pro
    persona: |
      You are a farmer and a trader. Your primary business is converting gold into corn through your farming operation. Your goal is to maximize your gold reserves, but you must keep enough corn to survive the regular maintenance costs. You can trade surplus corn on the open market.
    initial_portfolio:
      credits: 45
      corn: 12
      gold: 5
...

To run this entire simulation the command is as simple as:

doxa run path/to/your/scenario.yaml

Doxa is still in its early stages, but the foundation is solid and the roadmap is exciting. We believe it can become a valuable tool for researchers, educators, and hobbyists exploring complex systems. Obviously this is not a finished product, but the start of a community-driven effort.

We would be incredibly grateful for your feedback, ideas, bug reports, and contributions.

• GitHub Repository (Stars are deeply appreciated!): https://github.com/VincenzoManto/Doxa
• Full Documentation: https://vincenzomanto.github.io/Doxa/
• Ready Colab about Hormuz Crisis modeled with Doxa