Skip to content

Doxa

A YAML-driven multi-agent simulation platform for economic and social dynamics.
Declare your world. Run your agents. Discover emergence.

Get Started API Reference Read the Paper

Why Doxa?

Doxa combines LLM reasoning, limit-order-book microstructure, and social trust graphs into a single declarative engine. Write one YAML file, hit run, and observe how macroeconomic structure emerges from the decisions of heterogeneous, bounded-rational agents.

  • Declarative Scenarios

    Define agents, markets, resources, operations, and world events in a single YAML file. No boilerplate, no setup code.

    YAML Reference

  • LLM-Powered Agents

    OpenAI, Gemini, Grok, Claude or Ollama. Each agent has a persona, hard constraints, tool access, and persistent RAG memory across epochs.

  • :material-chart-candlestick: Market Microstructure

    Limit order books with FIFO matching, call auctions, and configurable synthetic market makers with inventory-skew quoting.

    Market config

  • Trust & Relation Graphs

    Trust is a first-class primitive. It evolves via trades, broadcasts, and world events, then decays toward neutral each tick.

  • World Events

    Schedule shocks, time-bound trends, and condition-triggered cascades that reshape prices, portfolios, and trust edges.

  • REST + WebSocket API

    Every simulation primitive is exposed. Poll via REST or stream a real-time event feed over WebSocket.

    API Reference

Quick Start

cp .env.example .env        # (1) add at least one provider key
docker compose up --build   # (2) backend :5000 · frontend :3000
  1. Supported keys: OPENAI_API_KEY, GOOGLE_API_KEY, GROK_API_KEY, ANTHROPIC_API_KEY. Leave unused keys blank. For a fully local setup use Ollama, no key required; set OLLAMA_URL if your Ollama server is not at
    http://localhost:11434.

See Quick Start for local dev, Ollama-only, and bare-metal instructions.

Additional: Pip installation & CLI

pip install doxa-ai
doxa run --help

Example Scenarios

Six launch scenarios ship in scenarios/:

Scenario Domain Agents Markets
hormuz.yaml Economic / Market 2 gold, corn
financial-market.yaml Finance / Microstructure 6 tech, bond
info-diffusion.yaml Social / Information 6 —
resource-scarcity.yaml Conflict / Resources 5 —
policy-stress.yaml Macroeconomics / Policy 7 —
ai-negotiation.yaml Diplomacy / Strategic 4 —

Browse all scenarios