Doxa – Ollama를 갖춘 경제적으로 제한된 ABM 시뮬레이터

Quick Start | Contributing | Code of Conduct | Paper | YAML Reference | Full Docs Doxa is a YAML-driven multi-agent simulation platform for economic and social systems. It combines LLM-backed agents, market microstructure, relation graphs, and world events behind a FastAPI API and a React client. - Copy .env.example to.env and add your provider keys. - For local development: - Backend: pip install -r server/requirements-dev.txt - Frontend: cd client && npm install - Start with Docker: docker compose up --build - Open http://localhost:3000 Do you want to just run Doxa without installation? Here our is the fastest way to get started. See QUICKSTART.md for the full setup flow. - Docker (backend + frontend) ( docker compose up --build ) - Local dev (backend + frontend) - Backend only (via PyPI package and CLI) ( pip install doxa-ai ) scenarios/hormuz.yaml — bilateral farmer-miner market with world shocksscenarios/info-diffusion.yaml — misinformation diffusion through a trust networkscenarios/financial-market.yaml — multi-trader market microstructure scenarioscenarios/resource-scarcity.yaml — cooperation versus conflict under water and food stressscenarios/policy-stress.yaml — central bank, banks, and firms under a liquidity shockscenarios/ai-negotiation.yaml — treaty negotiation and deterrence dynamics between states Doxa is a modular, extensible platform for multi-agent simulation, integrating generative AI, economic modeling, and social dynamics. This whitepaper presents the motivation, formal architecture, YAML-based scenario schema, agent logic, engine internals, API, and a detailed case study, providing a reproducible foundation for research in computational economics and AI-driven agent systems. Multi-agent systems (MAS) are fundamental for modeling complex phenomena in economics, social science, and artificial intelligence. However, most existing platforms lack a unified, declarative, and extensible approach to combine economic simulation, social relations, and modern AI-driven reasoning. Doxa addresses this gap by providing a rigorous, YAML-driven simulation engine with support for generative AI, market microstructure, and rich event dynamics. Agent-based modeling platforms such as NetLogo, MASON, and Repast have enabled decades of research, but typically lack native support for LLM-based reasoning and flexible market mechanisms. Recent frameworks (e.g., OpenAI Gym, PettingZoo) focus on RL environments but do not offer declarative scenario modeling or social/economic integration. Doxa uniquely combines: - Declarative YAML scenario specification - Generative AI integration (OpenAI, Google, Ollama, etc.) - Economic/market simulation (OTC, LOB, market makers) - Social trust and relation dynamics - Extensible API for real-time and batch control graph TD subgraph API Layer A1[FastAPI Server] A2[REST Endpoints] A3[WebSocket Endpoints] end subgraph Engine B1[DoxaEngine] B2[SimulationEnvironment] B3[DoxaAgent] B4[MarketEngine] B5[RelationGraph] B6[WorldEventScheduler] B7[ConsoleLogger] end subgraph Submodules C1[AgentEconomics] C2[AgentState] C3[Market] C4[Order] C5[WorldEventEffect] C6[RelationRecord] end subgraph Storage/External D1[RAG Memory] D2[LLM Providers] end %% API Layer A1 --> A2 A1 --> A3 A2 --> B1 A3 --> B1 %% Engine Core B1 --> B2 B1 --> B3 B1 --> B4 B1 --> B5 B1 --> B6 B1 --> B7 %% Submodules B3 --> C1 B3 --> C2 B4 --> C3 B4 --> C4 B5 --> C6 B6 --> C5 %% Storage/External B3 --> D1 B3 --> D2 %% Data Flows B2 -- manages --> B3 B2 -- manages --> B4 B2 -- manages --> B5 B2 -- manages --> B6 %% Events B6 -- triggers --> B3 B6 -- triggers --> B4 B6 -- triggers --> B5 %% Agents interact via API A3 -- real-time actions --> B3 %% Logging B7 -- logs --> A1 Doxa is composed of the following core modules (see server/engine/ ): - DoxaEngine: Orchestrates simulation, manages global state, and enforces rules. - SimulationEnvironment: Loads configuration, tracks portfolios, agents, trades, and RAG memory. - DoxaAgent: Implements agent logic, persona, constraints, and tool registration. - MarketEngine/Market: Handles market clearing, order books, and price dynamics. - RelationGraph/RelationRecord: Manages trust and social relations. - WorldEventScheduler/WorldEventEffect: Triggers and applies world events. - ConsoleLogger: Provides advanced logging for debugging and analysis. The architecture is modular, with each subsystem responsible for a specific aspect: economics, market, relations, communication, resources, events, and API integration. The scenario YAML file is the single source of truth for simulation configuration. It is strictly validated and supports the following top-level fields: global_rules : Simulation-wide settings (timing, maintenance, kill/victory conditions, constraints, operations, markets, relations, dynamics).actors : List of agent types, each with identity, persona, initial portfolio, constraints, operations, trading mode, and economic parameters.world_events : Optional list of scheduled or conditional events that affect resources, markets, or trust. See Section 8 for a concrete example (hormuz.yaml). flowchart TD A[Start: Load YAML Scenario] --> B[Validate Schema & Parameters] B --> C[Initialize SimulationEnvironment] C --> D[Instantiate Agents] D --> E[Initialize Markets & Relations] E --> F[Simulation Loop Epochs x Steps] F --> G[Apply Maintenance Costs] G --> H[Check Kill/Victory Conditions] H --> I[Agent Turns] I --> J[Market Clearing] J --> K[Apply World Events] K --> L[Update Trust & Relations] L --> M[Update Resource Portfolios] M --> N{More Steps?} N -- Yes --> G N -- No --> O{More Epochs?} O -- Yes --> F O -- No --> P[Collect Results & Logs] P --> Q[Expose via API/WS] Q --> R[End] %% Optional: highlight agent reasoning I --> I1[LLM Reasoning / RAG Query] I1 --> I %% Optional: highlight event triggers K --> K1[Conditional/Trend/Shock Evaluation] K1 --> K Each agent Let The trust graph Agents exchange messages Let World events The API exposes endpoints for scenario management, simulation control, and data streaming. REST endpoints support batch operations; WebSocket endpoints provide real-time updates for agent actions and resources. The engine enforces strict validation of scenario files (see CONFIG_YAML_REFERENCE.md): - Uniqueness of agent IDs - All referenced resources must be declared - Market and operation parameters must be feasible - Victory conditions must be reachable - All constraints and event triggers are checked for logical consistency The system is designed for reproducibility, extensibility, and modularity. All simulation runs are fully determined by the YAML and engine version. Doxa supports a wide range of research applications, including: - Economic market experiments (e.g., price discovery, liquidity shocks) - Social contagion and trust dynamics - AI-driven negotiation and coalition formation - Policy evaluation and stress testing See below for a concrete scenario (excerpt): global_rules: epochs: 1 steps: 12 execution_mode: sequential maintenance: corn: 2 kill_conditions: - resource: corn threshold: 0 victory_conditions: - resource: gold threshold: 34 relation_dynamics: on_trade_success: trust_delta: 0.03 on_trade_rejected: trust_delta: -0.02 on_broadcast: trust_delta: 0.01 trust_decay_rate: 0.01 panic_decay_rate: 0.05 relations: - source: player target: miners trust: 0.68 type: neutral - source: miners target: player trust: 0.58 type: neutral markets: - resource: gold currency: credits initial_price: 6.0 min_price: 1.0 max_price: 40.0 clearing: per_step - resource: corn currency: credits initial_price: 2.4 min_price: 0.5 max_price: 15.0 clearing: per_step world_events: - name: gold_spike type: shock trigger: tick: 4 effect: market: gold price_multiplier: 1.4 - name: corn_shortage type: shock trigger: tick: 6 effect: market: corn price_multiplier: 1.35 - name: panic_wave type: trend trigger: tick: 2 duration: 3 effect: targets: all resource: panic rate: 0.08 - name: food_relief type: conditional trigger: condition: resource: corn operator: lt threshold: 6 scope: any_agent effect: targets: all resource: corn delta: 3 actors: - id: player provider: google model_name: gemini-2.5-pro persona: | Farmer-trader. Your core business is converting gold into corn. Keep enough corn to survive maintenance and monetize surplus. trading_mode: both initial_portfolio: credits: 45 corn: 12 gold: 5 panic: 0.0 constraints: gold: min: 0 corn: min: 0 credits: min: 0 panic: min: 0 max: 1 operations: farm: input: gold: 1 output: corn: 4 - id: miners provider: google model_name: gemini-2.5-pro persona: | Miner-merchant. Your core business is converting corn into gold. Prefer the exchange over OTC: check the corn and gold books, post bids for corn before you run short, post asks for gold when inventory is ample, and use direct negotiation only when the book is empty or a bilateral trade is clearly better. Keep enough corn to continue mining. trading_mode: both initial_portfolio: credits: 55 corn: 6 gold: 16 panic: 0.0 constraints: gold: min: 0 corn: min: 0 credits: min: 0 panic: min: 0 max: 1 operations: mine: input: corn: 2 output: gold: 5 Doxa is designed for extensibility and reproducibility, but current limitations include scalability to very large agent populations, lack of native distributed execution, and reliance on external LLM APIs for advanced reasoning. Future work includes support for distributed simulation, richer agent cognition, and advanced visualization tools. Doxa provides a robust, extensible platform for multi-agent simulation, integrating economic, social, and AI-driven reasoning. Its YAML-based configuration, modular engine, and API make it suitable for a wide range of research applications. % [1] Wilensky, U. (1999). NetLogo. http://ccl.northwestern.edu/netlogo/ % [2] Luke, S., et al. (2005). MASON: A Multiagent Simulation Environment. Simulation, 81(7), 517-527. % [3] North, M.J., et al. (2013). Complex Adaptive Systems Modeling with Repast Simphony. Complex Adaptive Systems Modeling, 1(1), 3. % [4] Brockman, G., et al. (2016). OpenAI Gym. arXiv preprint arXiv:1606.01540. % [5] Terry, J.K., et al. (2020). PettingZoo: Multi-Agent Reinforcement Learning Environments. NeurIPS 2020.