the-grid-cc 1.1.0

package/core/energy.py

@@ -0,0 +1,267 @@
+"""
+Energy Management - Token/budget tracking for The Grid.
+
+"Programs need Energy to run on The Grid."
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+from enum import Enum
+import threading
+
+
+class EnergyLevel(Enum):
+    """Energy level thresholds."""
+    FULL = "full"           # > 80%
+    NORMAL = "normal"       # 40-80%
+    LOW = "low"             # 10-40%
+    CRITICAL = "critical"   # < 10%
+
+
+@dataclass
+class EnergyTransaction:
+    """Record of energy consumption or allocation."""
+    timestamp: datetime
+    entity_id: str
+    entity_type: str  # grid, cluster, block, thread, program
+    amount: int
+    action: str  # allocated, consumed, returned
+    balance_after: int
+    description: str = ""
+
+
+class EnergyPool:
+    """An energy pool for a Grid entity."""
+
+    def __init__(self, budget: int, name: str, parent: Optional["EnergyPool"] = None):
+        self.budget = budget
+        self.name = name
+        self.parent = parent
+        self.consumed = 0
+        self.allocated_to_children = 0
+        self.transactions: list[EnergyTransaction] = []
+        self._lock = threading.Lock()
+
+    @property
+    def available(self) -> int:
+        """Get available energy (not consumed or allocated to children)."""
+        return self.budget - self.consumed - self.allocated_to_children
+
+    @property
+    def remaining(self) -> int:
+        """Get remaining energy (budget minus consumed)."""
+        return self.budget - self.consumed
+
+    @property
+    def level(self) -> EnergyLevel:
+        """Get current energy level."""
+        pct = self.percentage
+        if pct > 80:
+            return EnergyLevel.FULL
+        elif pct > 40:
+            return EnergyLevel.NORMAL
+        elif pct > 10:
+            return EnergyLevel.LOW
+        else:
+            return EnergyLevel.CRITICAL
+
+    @property
+    def percentage(self) -> float:
+        """Get energy as percentage of budget."""
+        if self.budget == 0:
+            return 0.0
+        return (self.remaining / self.budget) * 100
+
+    def consume(self, amount: int, entity_id: str, description: str = "") -> bool:
+        """Consume energy from this pool."""
+        with self._lock:
+            if amount > self.available:
+                return False
+            self.consumed += amount
+            self._record_transaction(
+                entity_id=entity_id,
+                entity_type="consumer",
+                amount=amount,
+                action="consumed",
+                description=description,
+            )
+            return True
+
+    def allocate_to_child(self, amount: int, child_name: str) -> Optional["EnergyPool"]:
+        """Allocate energy to a child pool."""
+        with self._lock:
+            if amount > self.available:
+                return None
+            self.allocated_to_children += amount
+            child_pool = EnergyPool(budget=amount, name=child_name, parent=self)
+            self._record_transaction(
+                entity_id=child_name,
+                entity_type="child_pool",
+                amount=amount,
+                action="allocated",
+                description=f"Allocated to {child_name}",
+            )
+            return child_pool
+
+    def return_unused(self) -> int:
+        """Return unused energy to parent pool."""
+        if not self.parent:
+            return 0
+        with self._lock:
+            unused = self.available
+            if unused > 0:
+                self.parent.allocated_to_children -= unused
+                self.budget -= unused
+                self._record_transaction(
+                    entity_id=self.name,
+                    entity_type="pool",
+                    amount=unused,
+                    action="returned",
+                    description=f"Returned to {self.parent.name}",
+                )
+            return unused
+
+    def _record_transaction(
+        self,
+        entity_id: str,
+        entity_type: str,
+        amount: int,
+        action: str,
+        description: str = "",
+    ) -> None:
+        """Record an energy transaction."""
+        self.transactions.append(EnergyTransaction(
+            timestamp=datetime.now(),
+            entity_id=entity_id,
+            entity_type=entity_type,
+            amount=amount,
+            action=action,
+            balance_after=self.remaining,
+            description=description,
+        ))
+
+    def get_bar(self, width: int = 20) -> str:
+        """Get a visual energy bar."""
+        filled = int((self.percentage / 100) * width)
+        empty = width - filled
+        return "█" * filled + "░" * empty
+
+    def summary(self) -> str:
+        """Get energy summary."""
+        return (
+            f"{self.name}: {self.get_bar()} "
+            f"{self.remaining:,}/{self.budget:,} ({self.percentage:.0f}%)"
+        )
+
+
+class EnergyManager:
+    """
+    Manages energy (token budgets) across The Grid.
+
+    Energy flows:
+    Grid → Cluster → Block → Thread/Program
+
+    Each level can allocate energy to children but cannot
+    exceed its own budget.
+    """
+
+    def __init__(
+        self,
+        grid_budget: int = 10000,
+        cluster_budget: int = 2000,
+        block_budget: int = 500,
+        thread_budget: int = 100,
+        spawn_cost: int = 100,
+        low_threshold: float = 0.1,
+    ):
+        self.grid_budget = grid_budget
+        self.cluster_budget = cluster_budget
+        self.block_budget = block_budget
+        self.thread_budget = thread_budget
+        self.spawn_cost = spawn_cost
+        self.low_threshold = low_threshold
+
+        # Root energy pool
+        self.grid_pool = EnergyPool(budget=grid_budget, name="Grid")
+
+        # Track all pools
+        self.pools: dict[str, EnergyPool] = {"grid": self.grid_pool}
+
+    def create_cluster_pool(self, cluster_id: str) -> Optional[EnergyPool]:
+        """Create an energy pool for a new Cluster."""
+        pool = self.grid_pool.allocate_to_child(
+            amount=min(self.cluster_budget, self.grid_pool.available),
+            child_name=f"cluster:{cluster_id}",
+        )
+        if pool:
+            self.pools[f"cluster:{cluster_id}"] = pool
+        return pool
+
+    def create_block_pool(self, cluster_id: str, block_id: str) -> Optional[EnergyPool]:
+        """Create an energy pool for a new Block."""
+        cluster_pool = self.pools.get(f"cluster:{cluster_id}")
+        if not cluster_pool:
+            return None
+        pool = cluster_pool.allocate_to_child(
+            amount=min(self.block_budget, cluster_pool.available),
+            child_name=f"block:{block_id}",
+        )
+        if pool:
+            self.pools[f"block:{block_id}"] = pool
+        return pool
+
+    def create_thread_pool(self, block_id: str, thread_id: str) -> Optional[EnergyPool]:
+        """Create an energy pool for a new Thread."""
+        block_pool = self.pools.get(f"block:{block_id}")
+        if not block_pool:
+            return None
+        pool = block_pool.allocate_to_child(
+            amount=min(self.thread_budget, block_pool.available),
+            child_name=f"thread:{thread_id}",
+        )
+        if pool:
+            self.pools[f"thread:{thread_id}"] = pool
+        return pool
+
+    def consume(self, pool_id: str, amount: int, description: str = "") -> bool:
+        """Consume energy from a pool."""
+        pool = self.pools.get(pool_id)
+        if not pool:
+            return False
+        return pool.consume(amount, pool_id, description)
+
+    def get_pool(self, pool_id: str) -> Optional[EnergyPool]:
+        """Get a pool by ID."""
+        return self.pools.get(pool_id)
+
+    def is_low(self, pool_id: str) -> bool:
+        """Check if a pool is at low energy."""
+        pool = self.pools.get(pool_id)
+        if not pool:
+            return True
+        return pool.percentage <= (self.low_threshold * 100)
+
+    def grid_summary(self) -> str:
+        """Get full grid energy summary."""
+        lines = ["ENERGY FLOW", "═" * 40]
+        lines.append(self.grid_pool.summary())
+
+        # Show cluster pools
+        for pool_id, pool in self.pools.items():
+            if pool_id.startswith("cluster:"):
+                lines.append(f"  └─ {pool.summary()}")
+                # Show block pools under this cluster
+                for block_id, block_pool in self.pools.items():
+                    if block_id.startswith("block:") and block_pool.parent == pool:
+                        lines.append(f"       ├─ {block_pool.summary()}")
+
+        return "\n".join(lines)
+
+    def total_consumed(self) -> int:
+        """Get total energy consumed across all pools."""
+        return sum(pool.consumed for pool in self.pools.values())
+
+    def total_remaining(self) -> int:
+        """Get total remaining energy in grid."""
+        return self.grid_pool.remaining

package/core/grid.py

@@ -0,0 +1,326 @@
+"""
+The Grid - Main orchestration class.
+
+"The Grid. A digital frontier. I tried to picture clusters of information
+as they moved through the computer."
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Any
+from enum import Enum
+import uuid
+import yaml
+import json
+
+from .cluster import Cluster, ClusterStatus
+from .block import Block, BlockStatus
+from .thread import Thread, ThreadStatus
+from .program import Program, ProgramStatus
+from .recognizer import Recognizer, RecognizerType
+from .disc import IdentityDisc
+from .energy import EnergyManager, EnergyPool
+from .io_tower import IOTower, CheckpointReason, CheckpointContext
+
+
+class GridStatus(Enum):
+    """Status of The Grid."""
+    INITIALIZING = "initializing"
+    READY = "ready"
+    RUNNING = "running"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class GridConfig:
+    """Configuration for The Grid."""
+    # Fission control
+    max_depth: int = 4
+    max_concurrent: int = 8
+    energy_per_spawn: int = 100
+
+    # Energy budgets
+    grid_budget: int = 10000
+    cluster_budget: int = 2000
+    block_budget: int = 500
+    thread_budget: int = 100
+    low_energy_threshold: float = 0.1
+
+    # I/O Tower
+    require_at_depth: int = 3
+    require_before_commit: bool = True
+    require_on_error: bool = True
+    timeout_seconds: int = 300
+
+    # Display
+    tron_aesthetics: bool = True
+
+    @classmethod
+    def from_yaml(cls, path: Path) -> "GridConfig":
+        """Load config from YAML file."""
+        with open(path) as f:
+            data = yaml.safe_load(f)
+
+        fission = data.get("fission", {})
+        energy = data.get("energy", {})
+        io = data.get("io_towers", {})
+        display = data.get("display", {})
+
+        return cls(
+            max_depth=fission.get("max_depth", 4),
+            max_concurrent=fission.get("max_concurrent", 8),
+            energy_per_spawn=fission.get("energy_per_spawn", 100),
+            grid_budget=energy.get("grid_budget", 10000),
+            cluster_budget=energy.get("cluster_budget", 2000),
+            block_budget=energy.get("block_budget", 500),
+            thread_budget=energy.get("thread_budget", 100),
+            low_energy_threshold=energy.get("low_energy_threshold", 0.1),
+            require_at_depth=io.get("require_at_depth", 3),
+            require_before_commit=io.get("require_before_commit", True),
+            require_on_error=io.get("require_on_error", True),
+            timeout_seconds=io.get("timeout_seconds", 300),
+            tron_aesthetics=display.get("tron_aesthetics", True),
+        )
+
+
+class Grid:
+    """
+    The Grid - Main orchestration class.
+
+    The Grid is the digital frontier where Clusters, Blocks, Threads,
+    and Programs execute. It manages the entire execution hierarchy
+    and coordinates energy flow.
+    """
+
+    def __init__(
+        self,
+        name: str = "The Grid",
+        config: GridConfig = None,
+        config_path: Path = None,
+    ):
+        self.id = str(uuid.uuid4())[:8]
+        self.name = name
+        self.status = GridStatus.INITIALIZING
+        self.created_at = datetime.now()
+
+        # Load configuration
+        if config:
+            self.config = config
+        elif config_path and config_path.exists():
+            self.config = GridConfig.from_yaml(config_path)
+        else:
+            self.config = GridConfig()
+
+        # Energy management
+        self.energy = EnergyManager(
+            grid_budget=self.config.grid_budget,
+            cluster_budget=self.config.cluster_budget,
+            block_budget=self.config.block_budget,
+            thread_budget=self.config.thread_budget,
+            spawn_cost=self.config.energy_per_spawn,
+            low_threshold=self.config.low_energy_threshold,
+        )
+
+        # I/O Tower (human checkpoints)
+        self.io_tower = IOTower(
+            require_at_depth=self.config.require_at_depth,
+            require_before_commit=self.config.require_before_commit,
+            require_on_error=self.config.require_on_error,
+            timeout_seconds=self.config.timeout_seconds,
+        )
+
+        # Clusters
+        self.clusters: dict[str, Cluster] = {}
+
+        # Active Programs (for tracking concurrent execution)
+        self.active_programs: dict[str, Program] = {}
+
+        # Statistics
+        self.cycles_completed = 0
+        self.programs_spawned = 0
+        self.programs_derezzed = 0
+
+        self.status = GridStatus.READY
+
+    def create_cluster(
+        self,
+        name: str,
+        purpose: str,
+        description: str = "",
+    ) -> Cluster:
+        """Create a new Cluster on The Grid."""
+        cluster = Cluster(
+            name=name,
+            purpose=purpose,
+            description=description,
+        )
+
+        # Allocate energy
+        cluster.energy_pool = self.energy.create_cluster_pool(cluster.id)
+
+        self.clusters[cluster.id] = cluster
+        return cluster
+
+    def get_cluster(self, cluster_id: str) -> Optional[Cluster]:
+        """Get a Cluster by ID."""
+        return self.clusters.get(cluster_id)
+
+    def get_cluster_by_name(self, name: str) -> Optional[Cluster]:
+        """Get a Cluster by name."""
+        for cluster in self.clusters.values():
+            if cluster.name == name:
+                return cluster
+        return None
+
+    def spawn_program(
+        self,
+        name: str,
+        purpose: str,
+        parent: Program = None,
+        energy_budget: int = None,
+    ) -> Optional[Program]:
+        """Spawn a new Program on The Grid."""
+        if energy_budget is None:
+            energy_budget = self.config.energy_per_spawn
+
+        # Check concurrent limit
+        if len(self.active_programs) >= self.config.max_concurrent:
+            return None
+
+        # Check depth limit if parent exists
+        depth = 0 if parent is None else parent.depth + 1
+        if depth > self.config.max_depth:
+            return None
+
+        # Check if I/O Tower checkpoint needed
+        if self.io_tower.should_checkpoint(CheckpointReason.FISSION_DEPTH, depth):
+            context = CheckpointContext(
+                reason=CheckpointReason.FISSION_DEPTH,
+                program_id=parent.id if parent else "grid",
+                program_name=parent.name if parent else "Grid",
+                depth=depth,
+                energy_remaining=parent.disc.energy_remaining() if parent else self.energy.total_remaining(),
+                energy_allocated=parent.disc.energy_allocated if parent else self.config.grid_budget,
+                pending_actions=[f"Spawn Program: {name}"],
+                details={"purpose": purpose, "energy_cost": energy_budget},
+            )
+            # In actual use, this would pause for user input
+            # For now, we continue (checkpoint is logged)
+            self.io_tower.checkpoint(context)
+
+        program = Program(
+            name=name,
+            purpose=purpose,
+            parent=parent,
+            energy_budget=energy_budget,
+        )
+
+        self.active_programs[program.id] = program
+        self.programs_spawned += 1
+
+        return program
+
+    def derez_program(self, program: Program) -> None:
+        """Derez (terminate) a Program."""
+        program.derez()
+        if program.id in self.active_programs:
+            del self.active_programs[program.id]
+        self.programs_derezzed += 1
+
+    def start(self) -> None:
+        """Start Grid execution."""
+        self.status = GridStatus.RUNNING
+
+        # Start all pending clusters
+        for cluster in self.clusters.values():
+            if cluster.status == ClusterStatus.PENDING:
+                cluster.start()
+
+    def pause(self) -> None:
+        """Pause Grid execution."""
+        self.status = GridStatus.PAUSED
+
+    def resume(self) -> None:
+        """Resume Grid execution."""
+        if self.status == GridStatus.PAUSED:
+            self.status = GridStatus.RUNNING
+
+    def complete_cycle(self) -> None:
+        """Complete a cycle of execution."""
+        self.cycles_completed += 1
+
+    def is_complete(self) -> bool:
+        """Check if all work on The Grid is complete."""
+        return all(
+            c.status in (ClusterStatus.COMPLETED, ClusterStatus.DEREZZED)
+            for c in self.clusters.values()
+        )
+
+    def get_status_summary(self) -> dict:
+        """Get Grid status summary."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "status": self.status.value,
+            "clusters": len(self.clusters),
+            "active_programs": len(self.active_programs),
+            "programs_spawned": self.programs_spawned,
+            "programs_derezzed": self.programs_derezzed,
+            "cycles_completed": self.cycles_completed,
+            "energy_remaining": self.energy.total_remaining(),
+            "energy_consumed": self.energy.total_consumed(),
+        }
+
+    def energy_percentage(self) -> float:
+        """Get Grid energy as percentage."""
+        return self.energy.grid_pool.percentage
+
+    def get_energy_bar(self, width: int = 20) -> str:
+        """Get visual energy bar."""
+        return self.energy.grid_pool.get_bar(width)
+
+    def render_status(self) -> str:
+        """Render Grid status display."""
+        lines = [
+            "╔" + "═" * 77 + "╗",
+            "║" + " " * 77 + "║",
+            f"║   GRID STATUS         {self.get_energy_bar()}  {self.energy_percentage():.0f}% Energy" + " " * 22 + "║",
+            f"║   Active Programs     {len(self.active_programs):<54}║",
+            f"║   Clusters            {len(self.clusters):<54}║",
+            f"║   Cycles completed    {self.cycles_completed:<54}║",
+            "║" + " " * 77 + "║",
+        ]
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        """Serialize Grid to dictionary."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "status": self.status.value,
+            "created_at": self.created_at.isoformat(),
+            "config": {
+                "max_depth": self.config.max_depth,
+                "max_concurrent": self.config.max_concurrent,
+                "grid_budget": self.config.grid_budget,
+            },
+            "clusters": [c.to_dict() for c in self.clusters.values()],
+            "active_programs": [p.to_dict() for p in self.active_programs.values()],
+            "statistics": {
+                "cycles_completed": self.cycles_completed,
+                "programs_spawned": self.programs_spawned,
+                "programs_derezzed": self.programs_derezzed,
+                "energy_remaining": self.energy.total_remaining(),
+                "energy_consumed": self.energy.total_consumed(),
+            },
+        }
+
+    def to_json(self) -> str:
+        """Serialize Grid to JSON."""
+        return json.dumps(self.to_dict(), indent=2)
+
+    def __repr__(self) -> str:
+        return f"Grid(id={self.id}, name={self.name}, clusters={len(self.clusters)})"