How macaronquantum/ia-verse- works
Repo purpose
This is a backend for a virtual economic world driven by autonomous AI agents. The core loop is a simulation tick: agents perceive the world, choose actions, create businesses, earn/spend money, and interact with bank/market systems. The repo also includes a separate API Gateway layer for tool execution and external integrations.
Primary runtime surfaces
The main application entrypoint is app/main.py, exposing a FastAPI REST API for world management and simulation control. A separate worker process (run_worker.py) handles background agent execution and scheduled work. The repository also ships a browser-based dashboard in frontend/ and web/, typically served behind Nginx in Docker.
World simulation core
The simulation is organized around app/simulation/, app/world/, and app/economy/. These modules model world state, events, crises, production, markets, demand, reputation, and the simulation engine itself. The world tick is the central data flow: state advances, agents act, the economy updates, and downstream systems like banking, energy, and reputation are recalculated.
Autonomous agent subsystem
Agent behavior lives under app/agents/. This includes decision-making, planning, memory, personality, goals, scheduler, resource optimization, evolution, and worker pool orchestration. Agents appear to be built as composable decision systems rather than a single monolith: a factory creates agents, a loop executes them, and specialized components handle memory, strategy, tool selection, and execution.
Business and organization layer
app/business/, app/companies-like logic via the API, app/organizations/, app/institutions/, and app/humans/ model enterprises, jobs, task dispatching, and organizational entities. This layer connects agent activity to economic output: agents can found businesses, acquire inputs, produce goods, and sell through market mechanisms. The readme’s “startup evolution” and opportunity engines indicate a startup/business lifecycle on top of the base simulation.
Banking, wallets, and crypto settlement
Financial infrastructure is spread across app/crypto/, app/wallets/, app/storage/database.py, and integration clients for Solana/Stripe/Coinbase-style flows. The system supports encrypted wallet lifecycle, balance checks, transactions, and settlement flows. This matters architecturally because the simulation’s “energy core” is tied to real or simulated monetary balance, so wallet/bank state is a first-class dependency of agent survival.
API Gateway v10 as a separate boundary
app/api_gateway/ is its own subsystem with service registry, cost estimation, tool calling, and sandboxed execution. It has dedicated sandbox runners for Docker and WASM, plus adapters to tool manifests and external dependencies. This is a clear boundary between “simulation/world APIs” and “tool execution APIs”: the gateway governs what tools exist, how they are priced, and how they are safely executed.
Tooling and external integrations
app/tools/, app/integrations/, app/external/, and app/web/ support real-world actions such as browser automation, scraping, social posting, cloud services, messaging, and payment providers. The integration layer is intentionally adapter-based, so external services are isolated behind client modules and tool manifests. This is likely where the system crosses from simulated economy into real APIs.
Memory, sensing, and data ingestion
Agent/world perception is fed by app/sensing/ streams, app/data/market_intelligence.py, and memory stores in app/memory/. Persistent episodic/vector memory and market/news/social/web trend streams provide inputs to agent reasoning and opportunity discovery. Architecturally, this is the ingestion and context layer that transforms external signals into decision-making inputs.
LLM and local model runtime
app/llm/ contains local model management and provider adapters, including vLLM-style runtime support. The repo is designed for hybrid execution: some decisions can be made locally, some can route externally, and GPU deployment is supported via the Docker/GPU compose setup. This layer is important because it provides the reasoning backend for agents and tool orchestration.
Persistence and schema management
Data persistence is handled through app/persistence/, app/db/, app/storage/, and migrations in both Alembic and SQL migration directories. PostgreSQL is the primary durable store, with Redis used for runtime coordination in the Docker deployment. This gives the system two important state boundaries: long-lived simulation data in Postgres and transient coordination/cache in Redis.
Security, compliance, and auditability
app/security/, app/justice/, app/compliance, tamper logs, and quota/reputation tests indicate an explicit governance layer. The gateway adds RBAC-style headers, quota enforcement, reputation penalties, and tamper-evident usage logs. This is not just an app concern; it is part of the architecture because agent/tool execution is controlled through policy, auditing, and sandboxing.
Deployment topology
The default deployment is containerized: API, frontend, workers, Redis, and PostgreSQL are brought up together via Docker Compose. GPU-specific deployment swaps in model-serving support, while scripts under scripts/ cover gateway startup, simulation runs, model downloads, and environment bootstrap. This repo therefore has a multi-process architecture with explicit separation between HTTP serving, background simulation workers, state storage, and model execution.
Main entry points: api_gateway Gateway · agents Agents · main.py Main API · simulation Simulation
Components 18
Runtime surfaces
HTTP API, worker, and UI entrypoints
Simulation core
World, agents, economy, and business systems
- Simulation · Advances the world tick and coordinates simulation flow
app/simulation - World state · World state, crises, and event lifecycle
app/world - Agents · Decision, memory, planning, scheduling, and execution systems
app/agents - Economy · Markets, demand, production, reputation, and central bank
app/economy - Business · Opportunity discovery, startup evolution, and business metrics
app/business - Organizations · Institutional and organizational entities tied to the simulation
app/organizations
API gateway
Tool registry, pricing, sandbox, and external tool execution
- Gateway · Separate boundary for tool execution, costing, and policy
app/api_gateway - Registry · Tool registry and service discovery for gateway execution
app/api_gateway/registry.py - Sandbox · Isolated Docker and WASM tool runners
app/api_gateway/sandbox - Tools · Manifest-backed tools and adapter layer
app/api_gateway/tools
Platform services
Persistence, security, observability, and integrations
- Integrations · Third-party service clients and settlement adapters
app/integrations - Storage · Database, durable store, and migration-backed state
app/storage - Security · Permissions, tamper logging, and governance controls
app/security - Observability · Monitoring and metrics collection for runtime health
app/observability
Connections 21
- Frontend → Main API: control · Dashboard drives world and simulation actions
- Web shell → Frontend: serve · Nginx serves the browser application
- Main API → Simulation: tick control · API starts, stops, and inspects simulation flow
- Worker → Agents: run · Background execution processes agent workloads
- Simulation → World state: advance · Tick updates world state and events
- Simulation → Agents: orchestrate · Simulation coordinates agent decisions and actions
- Agents → Economy: act on · Agent actions affect markets, demand, and production
- Agents → Business: found · Agents create and evolve businesses
- Business → Economy: produce · Business output feeds the economic system
- Economy → World state: recalculate · Economic state feeds back into the world tick
- Organizations → Business: host · Organizations provide structure for enterprises and jobs
- Main API → Storage: persist · HTTP state changes are written durably
- Simulation → Storage: store · Simulation snapshots and state are persisted
- Agents → Security: govern · Agent/tool activity is constrained by policy
- Main API → Observability: emit · Operational and simulation metrics are exposed
- Gateway → Registry: resolve · Gateway looks up available tools and services
- Gateway → Sandbox: execute · Tool calls run inside isolated sandboxes
- Gateway → Tools: adapt · Manifests are translated into executable tools
- Tools → Integrations: call out · Tools delegate to external service clients
- Gateway → Security: enforce · Gateway applies access control and tamper logging
- Gateway → Storage: record · Gateway usage and billing state are persisted