World System Orchestration

This document details the architecture of the WorldSystem orchestrator and the WorldSystemBuilder that configures it. It also provides a guide for extending the simulation by adding new sectors.

WorldSystem - The Central Orchestrator

Purpose: The WorldSystem class is the heart of the simulation. It acts as a central orchestrator that manages the lifecycle of all sectors, coordinates their interactions, and executes the main simulation loop. It is designed to be dynamic, allowing sectors to be added or removed with minimal changes to the core logic.

Core Responsibilities:

  • Dynamic Sector Management: It uses a SECTOR_REGISTRY to dynamically initialize all configured sectors at the start of a simulation.

  • Simulation Loop (step method): It defines the precise order of operations for each simulation step, ensuring a logical and predictable flow of data and resources.

  • Power Allocation: It manages the critical task of distributing the power generated by the EnergySector among all other power-consuming sectors.

  • Coordination: It acts as the intermediary between the sectors, the EvaluationEngine, and the PolicyEngine.

Simulation Step Lifecycle

The WorldSystem.step() method executes the following sequence of operations in every simulation step:

  1. Aggregate Power Demand: It queries all power-consuming sectors (via their get_power_demand() method) to determine the total power needed for the step.

  2. Generate Power: It passes the total demand to the EnergySector, which runs its internal logic to determine how much power it can actually supply.

  3. Allocate Power: It takes the available_power from the EnergySector and distributes it among the consuming sectors using a fair allocation strategy (e.g., proportional to demand).

  4. Step All Sectors: It calls the step() method on each sector, providing it with its allocated power for the step.

  5. Collect Metrics: After all sectors have completed their operations, it calls get_metrics() on each one to gather the results of the step (e.g., resources produced, dust generated).

  6. Evaluate Performance: It passes the collected metrics to the EvaluationEngine, which calculates the current state of all system-wide metrics and scores them against performance goals.

  7. Apply Policies: It provides the complete EvaluationResult to the PolicyEngine, which then applies any necessary policy effects (like throttling) to the sectors for the next simulation step.

WorldSystemBuilder - The Configuration Factory

Purpose: The WorldSystemBuilder is a utility that translates the raw data from the database (world system documents, component templates, goals) into a single, clean configuration dictionary that the WorldSystem can directly use for initialization.

Architecture:

  • Main Function (build_world_system_config): This is the entry point. It loads the required documents from the database and orchestrates the build process.

  • Sector Builders: For each sector (e.g., EnergySectorBuilder, ScienceSectorBuilder), there is a dedicated builder class. Each builder is responsible for processing the relevant section of the world system document and constructing the configuration dictionary for its specific sector.

  • ComponentBuilder (Base Class): This base class provides common functionality, most importantly the _merge_config method, which intelligently combines a component instance from the world system document with its corresponding template from the component_templates collection.

  • GoalsSystemBuilder: A specialized builder that loads active goal documents and formats them into the structure required by the EvaluationEngine.

How to Add a New Sector

Adding a new sector to the simulation involves four main steps:

Step 1: Create the Sector Class

Create a new Python file for your sector (e.g., new_sector.py). The class must have the following methods to integrate with the WorldSystem:

# /proxima_model/sphere_engine/new_sector.py

class NewSector:
    def __init__(self, world, config, event_bus):
        self.world = world
        self.config = config
        self.event_bus = event_bus
        # ... your initialization logic ...

    def get_power_demand(self) -> float:
        # Return the power this sector needs for the current step
        return 100.0

    def step(self, allocated_power: float):
        # Execute the sector's logic for one step
        # Use allocated_power to determine what can be done
        pass

    def get_metrics(self) -> dict:
        # Return a dictionary of metrics for the evaluation engine
        return {
            "metric_contributions": {
                "IND-DUST-COV": 0.5 
            }
        }

Step 2: Create the Sector Builder

In world_system_builder.py, create a new builder class for your sector.

# /proxima_model/world_system/world_system_builder.py
# ... existing code ...

class NewSectorBuilder(ComponentBuilder):
    def build(self, components: List[Dict[str, Any]]) -> Dict[str, Any]:
        config = {"sector_name": "new_sector", "some_parameter": "default"}
        # ... your logic to process components and build the config dict ...
        logger.info("✅ Configured new sector")
        return config

Step 3: Register the Sector in WorldSystem

In world_system.py, import your new sector class and add it to the SECTOR_REGISTRY.

# /proxima_model/world_system/world_system.py
# ... existing code ...
from proxima_model.sphere_engine.construction_sector import ConstructionSector
from proxima_model.sphere_engine.new_sector import NewSector # <-- IMPORT

class WorldSystem(Model):
    SECTOR_REGISTRY = {
        "energy": EnergySector,
        "science": ScienceSector,
        "manufacturing": ManufacturingSector,
        "equipment_manufacturing": EquipmentManSector,
        "transportation": TransportationSector,
        "construction": ConstructionSector,
        "new_sector": NewSector, # <-- REGISTER
    }
    # ... existing code ...

Step 4: Integrate the Builder

In world_system_builder.py, at the end of the build_world_system_config function, instantiate and run your new builder.

# /proxima_model/world_system/world_system_builder.py
# ... existing code ...

def build_world_system_config(...):
    # ... existing builder calls ...

    construction_builder = ConstructionSectorBuilder(component_templates)
    config["agents_config"]["construction"] = construction_builder.build(components_dict.get("construction", []))

    # Add your new builder here
    new_sector_builder = NewSectorBuilder(component_templates)
    config["agents_config"]["new_sector"] = new_sector_builder.build(components_dict.get("new_sector", []))

    # Build goals configuration
    goals_builder = GoalsSystemBuilder(db)
    # ... existing code ...

Finally, you would add a "new_sector": [...] section to your world system JSON configuration file to define its components, and the builder will process it on the next run.