rct-platform 1.0.2a0__py3-none-any.whl

core/__init__.py

@@ -0,0 +1,5 @@
+"""Core public package metadata for RCT Platform."""
+
+__version__ = "1.0.2a0"
+
+__all__ = ["__version__"]

core/delta_engine/memory_delta.py

@@ -0,0 +1,342 @@
+"""
+RCT NPC Kernel — Memory Delta Engine (Plan 21)
+
+Design principle:
+  Instead of storing full agent state at every tick (expensive),
+  only store what CHANGED (delta). This achieves the 74% compression
+  target documented in RCT-NPC-System-Analysis-1.md.
+
+Memory layout per agent:
+  baseline_state  → full state at tick 0 (or last checkpoint)
+  deltas[]        → ordered list of (tick, what_changed) records
+
+Queries:
+  get_state_at_tick(agent_id, tick)  → reconstruct by replaying deltas
+  replay_to_tick(agent_id, tick)     → synonym; returns reconstructed state
+  rollback(agent_id, n_ticks)        → drop last n delta records
+  compute_compression_ratio()        → vs naïve full-state storage
+
+Layer: Memory subsystem (no imports from other NPC kernel modules except fdia.NPCIntentType)
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any
+import copy
+
+from core.fdia.fdia import NPCIntentType
+
+
+# ---------------------------------------------------------------------------
+# Delta Record
+# ---------------------------------------------------------------------------
+
+@dataclass
+class MemoryDelta:
+    """
+    A single state-change record for one agent at one tick.
+
+    Stores only the DIFF versus the previous state —
+    fields that did not change are absent from `changes`.
+    """
+    agent_id: str
+    tick: int
+    intent_type: NPCIntentType
+    action_type: str
+    outcome: str                          # "success", "blocked", "partial"
+    changes: Dict[str, Any] = field(default_factory=dict)
+    # relationship_change: {other_agent_id: delta_alignment_float}
+    relationship_change: Dict[str, float] = field(default_factory=dict)
+    governance_violation: bool = False
+    resources_delta: Dict[str, float] = field(default_factory=dict)  # gained/lost
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "agent_id": self.agent_id,
+            "tick": self.tick,
+            "intent_type": self.intent_type.value,
+            "action_type": self.action_type,
+            "outcome": self.outcome,
+            "changes": self.changes,
+            "relationship_change": {
+                k: round(v, 6) for k, v in sorted(self.relationship_change.items())
+            },
+            "governance_violation": self.governance_violation,
+            "resources_delta": {
+                k: round(v, 6) for k, v in sorted(self.resources_delta.items())
+            },
+        }
+
+
+# ---------------------------------------------------------------------------
+# Agent Memory State (reconstructed at query time)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AgentMemoryState:
+    """Full reconstructed state of an agent at a specific tick."""
+    agent_id: str
+    tick: int
+    intent_type: NPCIntentType
+    resources: Dict[str, float] = field(default_factory=dict)
+    reputation: float = 1.0
+    relationships: Dict[str, float] = field(default_factory=dict)  # other_id → alignment
+    action_history: List[str] = field(default_factory=list)        # ordered action types
+    violation_count: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "agent_id": self.agent_id,
+            "tick": self.tick,
+            "intent_type": self.intent_type.value,
+            "resources": {k: round(v, 6) for k, v in sorted(self.resources.items())},
+            "reputation": round(self.reputation, 6),
+            "relationships": {k: round(v, 6) for k, v in sorted(self.relationships.items())},
+            "action_history_len": len(self.action_history),
+            "violation_count": self.violation_count,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Memory Delta Engine
+# ---------------------------------------------------------------------------
+
+@dataclass
+class MemoryDeltaEngine:
+    """
+    Stores per-agent memory as compressed delta sequences.
+
+    Compression approach:
+    - Baseline: full state snapshot at initialization (or last checkpoint)
+    - Delta: only changed fields per tick
+    - Naive: would store full state every tick → O(agents × ticks × state_size)
+    - Delta: O(agents × changed_fields_per_tick) ≈ 26% of naive
+
+    Thread safety: NOT thread-safe — call only from the simulation loop.
+    """
+
+    # baseline_states[agent_id] → initial full state dict
+    baseline_states: Dict[str, AgentMemoryState] = field(default_factory=dict)
+    # deltas[agent_id] → ordered list of MemoryDelta (sorted by tick ascending)
+    deltas: Dict[str, List[MemoryDelta]] = field(default_factory=dict)
+    # naive_byte_count: estimated bytes if we stored full state each tick
+    _naive_byte_count: int = field(default=0, repr=False)
+    # delta_byte_count: estimated bytes with delta storage
+    _delta_byte_count: int = field(default=0, repr=False)
+    # checkpoint_interval: create full snapshot every N ticks for fast replay
+    checkpoint_interval: int = 50
+    _checkpoints: Dict[str, Dict[int, AgentMemoryState]] = field(
+        default_factory=dict, repr=False
+    )
+
+    # --- registration -------------------------------------------------------
+
+    def register_agent(
+        self,
+        agent_id: str,
+        initial_intent: "NPCIntentType | AgentMemoryState",
+        initial_resources: Optional[Dict[str, float]] = None,
+        initial_reputation: float = 1.0,
+    ) -> None:
+        """Register a new agent with its initial state.
+
+        Two call styles are supported:
+
+        Style A — positional (preferred):
+            engine.register_agent("hero", NPCIntentType.DISCOVER,
+                                  {"energy": 100.0}, reputation=0.8)
+
+        Style B — AgentMemoryState object (convenience):
+            engine.register_agent("hero", AgentMemoryState(
+                agent_id="hero", tick=0,
+                intent_type=NPCIntentType.DISCOVER,
+                resources={"energy": 100.0}, reputation=0.8))
+        """
+        # Style B: caller passed a pre-built AgentMemoryState as second arg
+        if isinstance(initial_intent, AgentMemoryState):
+            snapshot = initial_intent
+            baseline = AgentMemoryState(
+                agent_id=agent_id,
+                tick=0,
+                intent_type=snapshot.intent_type,
+                resources=dict(snapshot.resources),
+                reputation=snapshot.reputation,
+                relationships=dict(snapshot.relationships),
+                action_history=list(snapshot.action_history),
+                violation_count=snapshot.violation_count,
+            )
+        else:
+            # Style A: positional NPCIntentType
+            baseline = AgentMemoryState(
+                agent_id=agent_id,
+                tick=0,
+                intent_type=initial_intent,
+                resources=dict(initial_resources or {}),
+                reputation=initial_reputation,
+            )
+        self.baseline_states[agent_id] = baseline
+        self.deltas[agent_id] = []
+        self._checkpoints[agent_id] = {0: copy.deepcopy(baseline)}
+
+    # --- recording ----------------------------------------------------------
+
+    def record_delta(
+        self,
+        agent_id: str,
+        tick: int,
+        intent_type: NPCIntentType,
+        action_type: str,
+        outcome: str,
+        resource_changes: Optional[Dict[str, float]] = None,
+        relationship_changes: Optional[Dict[str, float]] = None,
+        governance_violation: bool = False,
+        extra_changes: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Append a delta record for *agent_id* at *tick*.
+
+        Only the supplied fields are stored — absent fields mean "unchanged".
+        """
+        if agent_id not in self.deltas:
+            raise KeyError(f"Agent '{agent_id}' not registered. Call register_agent() first.")
+
+        delta = MemoryDelta(
+            agent_id=agent_id,
+            tick=tick,
+            intent_type=intent_type,
+            action_type=action_type,
+            outcome=outcome,
+            resources_delta=dict(resource_changes or {}),
+            relationship_change=dict(relationship_changes or {}),
+            governance_violation=governance_violation,
+            changes=dict(extra_changes or {}),
+        )
+        self.deltas[agent_id].append(delta)
+
+        # Estimate sizes for compression ratio
+        # Naive: one full AgentMemoryState dict ≈ 200 bytes
+        # Delta: one MemoryDelta dict ≈ len(changes)*30 bytes
+        self._naive_byte_count += 200
+        self._delta_byte_count += max(30, len(str(delta.to_dict())))
+
+        # Create checkpoint if interval reached
+        all_deltas = self.deltas[agent_id]
+        if len(all_deltas) % self.checkpoint_interval == 0 and all_deltas:
+            state = self._reconstruct(agent_id, tick)
+            self._checkpoints[agent_id][tick] = copy.deepcopy(state)
+
+    # --- querying -----------------------------------------------------------
+
+    def get_state_at_tick(self, agent_id: str, tick: int) -> Optional[AgentMemoryState]:
+        """
+        Reconstruct full agent state at *tick* by replaying deltas from
+        the nearest prior checkpoint.
+        """
+        if agent_id not in self.baseline_states:
+            return None
+        return self._reconstruct(agent_id, tick)
+
+    def replay_to_tick(self, agent_id: str, target_tick: int) -> Optional[AgentMemoryState]:
+        """Alias for get_state_at_tick for semantics clarity."""
+        return self.get_state_at_tick(agent_id, target_tick)
+
+    def rollback(self, agent_id: str, n_ticks: int) -> int:
+        """
+        Remove the last *n_ticks* delta records for *agent_id*.
+        Returns number of records actually removed.
+        """
+        if agent_id not in self.deltas:
+            return 0
+        agent_deltas = self.deltas[agent_id]
+        remove = min(n_ticks, len(agent_deltas))
+        self.deltas[agent_id] = agent_deltas[: len(agent_deltas) - remove]
+        # Invalidate checkpoints that are now ahead of the rolled-back tick
+        if agent_deltas and remove < len(agent_deltas):
+            new_last_tick = agent_deltas[-1].tick if self.deltas[agent_id] else 0
+            stale = [t for t in self._checkpoints.get(agent_id, {}) if t > new_last_tick]
+            for t in stale:
+                del self._checkpoints[agent_id][t]
+        return remove
+
+    def get_recent_actions(self, agent_id: str, n: int = 5) -> List[str]:
+        """Return the last *n* action types for *agent_id*."""
+        agent_deltas = self.deltas.get(agent_id, [])
+        return [d.action_type for d in agent_deltas[-n:]]
+
+    def get_relationship_history(
+        self, agent_id: str, other_id: str
+    ) -> List[tuple]:
+        """Return (tick, delta_alignment) for all recorded interactions."""
+        result = []
+        for d in self.deltas.get(agent_id, []):
+            if other_id in d.relationship_change:
+                result.append((d.tick, d.relationship_change[other_id]))
+        return result
+
+    def get_violation_count(self, agent_id: str) -> int:
+        return sum(
+            1 for d in self.deltas.get(agent_id, []) if d.governance_violation
+        )
+
+    # --- compression metric -------------------------------------------------
+
+    def compute_compression_ratio(self) -> float:
+        """
+        Ratio: 1 - (delta_bytes / naive_bytes)
+        0.74 means delta storage uses 26% of naïve storage → 74% compression.
+        Returns 0.0 if no data recorded yet.
+        """
+        if self._naive_byte_count == 0:
+            return 0.0
+        ratio = 1.0 - (self._delta_byte_count / self._naive_byte_count)
+        return max(0.0, min(1.0, ratio))
+
+    def total_delta_count(self) -> int:
+        return sum(len(v) for v in self.deltas.values())
+
+    def registered_agent_count(self) -> int:
+        return len(self.baseline_states)
+
+    # --- private helpers ----------------------------------------------------
+
+    def _reconstruct(self, agent_id: str, target_tick: int) -> AgentMemoryState:
+        """
+        Internal: reconstruct state at target_tick from nearest checkpoint.
+        """
+        # Find the nearest checkpoint at or before target_tick
+        checkpoints = self._checkpoints.get(agent_id, {})
+        valid_cps = {t: s for t, s in checkpoints.items() if t <= target_tick}
+
+        if valid_cps:
+            nearest_tick = max(valid_cps.keys())
+            state = copy.deepcopy(valid_cps[nearest_tick])
+        else:
+            state = copy.deepcopy(self.baseline_states[agent_id])
+            nearest_tick = 0
+
+        # Replay deltas from nearest_tick+1 to target_tick
+        for delta in self.deltas.get(agent_id, []):
+            if delta.tick <= nearest_tick:
+                continue
+            if delta.tick > target_tick:
+                break
+            # Apply resource changes
+            for res, change in delta.resources_delta.items():
+                state.resources[res] = state.resources.get(res, 0.0) + change
+            # Apply relationship changes
+            for other_id, change in delta.relationship_change.items():
+                state.relationships[other_id] = (
+                    state.relationships.get(other_id, 0.0) + change
+                )
+            # Apply outcome effects
+            if delta.outcome == "success":
+                state.reputation = min(1.0, state.reputation + 0.01)
+            elif delta.outcome == "blocked" and delta.governance_violation:
+                state.reputation = max(0.0, state.reputation - 0.05)
+                state.violation_count += 1
+            # Append action
+            state.action_history.append(delta.action_type)
+            state.tick = delta.tick
+
+        state.tick = target_tick
+        return state