# 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`:

```python
# /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.

```python
# /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`.

```python
# /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.

```python
# /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.