crca 1.4.0__py3-none-any.whl

utils/ledger.py

@@ -0,0 +1,311 @@
+"""Event-sourced ledger for policy engine.
+
+This module provides a SQLite-based append-only event store for the policy engine.
+The ledger serves as:
+- Dataset for online learning
+- Audit trail for decisions
+- Replay engine for deterministic execution
+
+All events are hashed and stored immutably (append-only).
+"""
+
+import sqlite3
+import json
+from typing import Any, Dict, List, Optional
+from datetime import datetime
+from loguru import logger
+
+from schemas.policy import LedgerEvent
+
+
+class Ledger:
+    """SQLite-based append-only event ledger.
+    
+    Schema:
+        events(
+            id INTEGER PRIMARY KEY,
+            type TEXT,
+            epoch INTEGER,
+            hash TEXT UNIQUE,
+            payload_json TEXT
+        )
+    
+    Indexed on (epoch, type) for fast window queries.
+    """
+    
+    def __init__(self, db_path: str):
+        """
+        Initialize ledger with SQLite database.
+        
+        Args:
+            db_path: Path to SQLite database file
+        """
+        self.db_path = db_path
+        self._conn: Optional[sqlite3.Connection] = None
+        self._initialize_db()
+    
+    def _initialize_db(self) -> None:
+        """Initialize database schema if it doesn't exist."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        # Create events table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS events (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                type TEXT NOT NULL,
+                epoch INTEGER NOT NULL,
+                hash TEXT UNIQUE NOT NULL,
+                payload_json TEXT NOT NULL,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+        
+        # Create indexes for fast queries
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_epoch_type 
+            ON events(epoch, type)
+        """)
+        
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_epoch 
+            ON events(epoch)
+        """)
+        
+        conn.commit()
+        conn.close()
+    
+    def _get_connection(self) -> sqlite3.Connection:
+        """Get or create database connection."""
+        if self._conn is None:
+            self._conn = sqlite3.connect(self.db_path)
+            self._conn.row_factory = sqlite3.Row
+        return self._conn
+    
+    def append(self, event: LedgerEvent) -> int:
+        """
+        Append an event to the ledger.
+        
+        Args:
+            event: LedgerEvent to append
+            
+        Returns:
+            int: Event ID
+            
+        Raises:
+            sqlite3.IntegrityError: If hash already exists (duplicate event)
+        """
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        
+        try:
+            cursor.execute("""
+                INSERT INTO events (type, epoch, hash, payload_json)
+                VALUES (?, ?, ?, ?)
+            """, (
+                event.type,
+                event.epoch,
+                event.hash,
+                json.dumps(event.payload)
+            ))
+            conn.commit()
+            event_id = cursor.lastrowid
+            logger.debug(f"Appended event {event_id} (type={event.type}, epoch={event.epoch})")
+            return event_id
+        except sqlite3.IntegrityError as e:
+            if "UNIQUE constraint failed" in str(e):
+                logger.warning(f"Duplicate event hash {event.hash} - skipping")
+                # Return existing event ID
+                cursor.execute("SELECT id FROM events WHERE hash = ?", (event.hash,))
+                row = cursor.fetchone()
+                return row["id"] if row else -1
+            raise
+    
+    def window(self, epoch: int, k: int, event_type: Optional[str] = None) -> List[Dict[str, Any]]:
+        """
+        Get events from the last k epochs ending at epoch.
+        
+        Args:
+            epoch: End epoch (inclusive)
+            k: Number of epochs to look back
+            event_type: Optional event type filter
+            
+        Returns:
+            List[Dict[str, Any]]: List of event dictionaries
+        """
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        
+        start_epoch = max(0, epoch - k + 1)
+        
+        if event_type:
+            cursor.execute("""
+                SELECT * FROM events
+                WHERE epoch >= ? AND epoch <= ? AND type = ?
+                ORDER BY epoch ASC, id ASC
+            """, (start_epoch, epoch, event_type))
+        else:
+            cursor.execute("""
+                SELECT * FROM events
+                WHERE epoch >= ? AND epoch <= ?
+                ORDER BY epoch ASC, id ASC
+            """, (start_epoch, epoch))
+        
+        rows = cursor.fetchall()
+        events = []
+        for row in rows:
+            events.append({
+                "id": row["id"],
+                "type": row["type"],
+                "epoch": row["epoch"],
+                "hash": row["hash"],
+                "payload": json.loads(row["payload_json"]),
+                "created_at": row["created_at"]
+            })
+        
+        return events
+    
+    def latest(self, event_type: Optional[str] = None, epoch: Optional[int] = None) -> Optional[Dict[str, Any]]:
+        """
+        Get the latest event (optionally filtered by type and epoch).
+        
+        Args:
+            event_type: Optional event type filter
+            epoch: Optional epoch filter
+            
+        Returns:
+            Optional[Dict[str, Any]]: Latest event or None
+        """
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        
+        if event_type and epoch is not None:
+            cursor.execute("""
+                SELECT * FROM events
+                WHERE type = ? AND epoch = ?
+                ORDER BY id DESC
+                LIMIT 1
+            """, (event_type, epoch))
+        elif event_type:
+            cursor.execute("""
+                SELECT * FROM events
+                WHERE type = ?
+                ORDER BY epoch DESC, id DESC
+                LIMIT 1
+            """, (event_type,))
+        elif epoch is not None:
+            cursor.execute("""
+                SELECT * FROM events
+                WHERE epoch = ?
+                ORDER BY id DESC
+                LIMIT 1
+            """, (epoch,))
+        else:
+            cursor.execute("""
+                SELECT * FROM events
+                ORDER BY epoch DESC, id DESC
+                LIMIT 1
+            """)
+        
+        row = cursor.fetchone()
+        if row:
+            return {
+                "id": row["id"],
+                "type": row["type"],
+                "epoch": row["epoch"],
+                "hash": row["hash"],
+                "payload": json.loads(row["payload_json"]),
+                "created_at": row["created_at"]
+            }
+        return None
+    
+    def iter_range(
+        self,
+        t0: int,
+        t1: int,
+        event_type: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """
+        Iterate over events in epoch range [t0, t1] (inclusive).
+        
+        Args:
+            t0: Start epoch (inclusive)
+            t1: End epoch (inclusive)
+            event_type: Optional event type filter
+            
+        Returns:
+            List[Dict[str, Any]]: List of event dictionaries
+        """
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        
+        if event_type:
+            cursor.execute("""
+                SELECT * FROM events
+                WHERE epoch >= ? AND epoch <= ? AND type = ?
+                ORDER BY epoch ASC, id ASC
+            """, (t0, t1, event_type))
+        else:
+            cursor.execute("""
+                SELECT * FROM events
+                WHERE epoch >= ? AND epoch <= ?
+                ORDER BY epoch ASC, id ASC
+            """, (t0, t1))
+        
+        rows = cursor.fetchall()
+        events = []
+        for row in rows:
+            events.append({
+                "id": row["id"],
+                "type": row["type"],
+                "epoch": row["epoch"],
+                "hash": row["hash"],
+                "payload": json.loads(row["payload_json"]),
+                "created_at": row["created_at"]
+            })
+        
+        return events
+    
+    def compute_deltas(self, epoch: int) -> Dict[str, float]:
+        """
+        Compute feature deltas between observation and outcome at epoch t.
+        
+        Args:
+            epoch: Epoch to compute deltas for
+            
+        Returns:
+            Dict[str, float]: Dictionary mapping metric names to deltas
+        """
+        obs = self.latest(event_type="observation", epoch=epoch)
+        outcome = self.latest(event_type="outcome", epoch=epoch)
+        
+        if not obs or not outcome:
+            return {}
+        
+        obs_metrics = obs["payload"].get("metrics", {})
+        outcome_metrics = outcome["payload"].get("metrics", {})
+        
+        deltas = {}
+        all_metrics = set(obs_metrics.keys()) | set(outcome_metrics.keys())
+        
+        for metric in all_metrics:
+            obs_val = obs_metrics.get(metric, 0.0)
+            outcome_val = outcome_metrics.get(metric, 0.0)
+            deltas[metric] = outcome_val - obs_val
+        
+        return deltas
+    
+    def close(self) -> None:
+        """Close database connection."""
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()
+

utils/out_types.py

@@ -0,0 +1,16 @@
+"""
+Output type definitions for history and conversation formatting.
+
+Defines type literals for specifying output formats when extracting
+conversation history or agent responses.
+"""
+
+from typing import Literal
+
+HistoryOutputType = Literal[
+    "list", "dict", "dictionary", "string", "str", "final", "last",
+    "json", "all", "yaml", "xml", "dict-all-except-first",
+    "str-all-except-first", "basemodel", "dict-final", "list-final"
+]
+
+OutputType = HistoryOutputType

utils/rollback.py

@@ -0,0 +1,339 @@
+"""Rollback system for intervention recovery.
+
+Provides checkpoint creation, intervention recording, and rollback
+execution for recovering from failed interventions.
+"""
+
+from typing import Any, Dict, List, Optional
+from datetime import datetime, timezone
+import sqlite3
+import json
+import uuid
+from loguru import logger
+
+from schemas.policy import InterventionSpec
+
+
+class RollbackManager:
+    """Rollback manager for intervention recovery.
+    
+    Features:
+    - State checkpoint creation
+    - Intervention recording with results
+    - Rollback execution (reverse interventions)
+    - Checkpoint restoration
+    - Time-based retention
+    """
+    
+    def __init__(self, db_path: str = ":memory:", retention_days: int = 7):
+        """
+        Initialize rollback manager.
+        
+        Args:
+            db_path: Path to SQLite database (or ":memory:" for in-memory)
+            retention_days: Number of days to retain checkpoints
+        """
+        self.db_path = db_path
+        self.retention_days = retention_days
+        self.conn = sqlite3.connect(db_path)
+        self._init_db()
+    
+    def _init_db(self) -> None:
+        """Initialize database schema."""
+        cursor = self.conn.cursor()
+        
+        # Checkpoints table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS checkpoints (
+                checkpoint_id TEXT PRIMARY KEY,
+                epoch INTEGER NOT NULL,
+                state_json TEXT NOT NULL,
+                created_at TIMESTAMP NOT NULL
+            )
+        """)
+        
+        # Interventions table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS interventions (
+                intervention_id TEXT PRIMARY KEY,
+                checkpoint_id TEXT,
+                epoch INTEGER NOT NULL,
+                lever_id TEXT NOT NULL,
+                parameters_json TEXT NOT NULL,
+                result_json TEXT,
+                rollback_descriptor_json TEXT,
+                created_at TIMESTAMP NOT NULL,
+                FOREIGN KEY (checkpoint_id) REFERENCES checkpoints(checkpoint_id)
+            )
+        """)
+        
+        # Rollback history table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS rollback_history (
+                rollback_id TEXT PRIMARY KEY,
+                epoch INTEGER NOT NULL,
+                n_steps INTEGER NOT NULL,
+                intervention_ids TEXT NOT NULL,
+                created_at TIMESTAMP NOT NULL
+            )
+        """)
+        
+        self.conn.commit()
+    
+    def create_checkpoint(self, epoch: int, state: Dict[str, Any]) -> str:
+        """
+        Create a state checkpoint.
+        
+        Args:
+            epoch: Epoch number
+            state: State dictionary to checkpoint
+            
+        Returns:
+            str: Checkpoint ID
+        """
+        checkpoint_id = str(uuid.uuid4())
+        state_json = json.dumps(state)
+        created_at = datetime.now(timezone.utc).isoformat()
+        
+        cursor = self.conn.cursor()
+        cursor.execute("""
+            INSERT INTO checkpoints (checkpoint_id, epoch, state_json, created_at)
+            VALUES (?, ?, ?, ?)
+        """, (checkpoint_id, epoch, state_json, created_at))
+        self.conn.commit()
+        
+        logger.info(f"Created checkpoint {checkpoint_id} for epoch {epoch}")
+        
+        # Clean up old checkpoints
+        self._cleanup_old_checkpoints()
+        
+        return checkpoint_id
+    
+    def record_intervention(
+        self,
+        epoch: int,
+        intervention: InterventionSpec,
+        result: Optional[Dict[str, Any]] = None,
+        checkpoint_id: Optional[str] = None
+    ) -> str:
+        """
+        Record an intervention with its result.
+        
+        Args:
+            epoch: Epoch number
+            intervention: Intervention specification
+            result: Optional execution result
+            checkpoint_id: Optional checkpoint ID associated with this intervention
+            
+        Returns:
+            str: Intervention ID
+        """
+        intervention_id = str(uuid.uuid4())
+        parameters_json = json.dumps(intervention.parameters)
+        result_json = json.dumps(result) if result else None
+        rollback_descriptor_json = json.dumps(intervention.rollback_descriptor) if intervention.rollback_descriptor else None
+        created_at = datetime.now(timezone.utc).isoformat()
+        
+        cursor = self.conn.cursor()
+        cursor.execute("""
+            INSERT INTO interventions (
+                intervention_id, checkpoint_id, epoch, lever_id,
+                parameters_json, result_json, rollback_descriptor_json, created_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            intervention_id, checkpoint_id, epoch, intervention.lever_id,
+            parameters_json, result_json, rollback_descriptor_json, created_at
+        ))
+        self.conn.commit()
+        
+        logger.debug(f"Recorded intervention {intervention_id} for epoch {epoch}")
+        
+        return intervention_id
+    
+    def rollback(
+        self,
+        epoch: int,
+        n_steps: int,
+        actuator_registry: Optional[Any] = None
+    ) -> List[str]:
+        """
+        Rollback last N interventions.
+        
+        Args:
+            epoch: Current epoch
+            n_steps: Number of steps to rollback
+            actuator_registry: Optional actuator registry for executing rollbacks
+            
+        Returns:
+            List[str]: List of intervention IDs that were rolled back
+        """
+        cursor = self.conn.cursor()
+        
+        # Get last N interventions (most recent first)
+        cursor.execute("""
+            SELECT intervention_id, lever_id, parameters_json, rollback_descriptor_json
+            FROM interventions
+            WHERE epoch <= ?
+            ORDER BY created_at DESC
+            LIMIT ?
+        """, (epoch, n_steps))
+        
+        interventions = cursor.fetchall()
+        
+        if not interventions:
+            logger.warning(f"No interventions found to rollback (epoch {epoch}, n_steps {n_steps})")
+            return []
+        
+        rolled_back_ids = []
+        
+        # Execute rollbacks in reverse order (oldest first)
+        for intervention_id, lever_id, parameters_json, rollback_descriptor_json in reversed(interventions):
+            try:
+                if rollback_descriptor_json:
+                    rollback_descriptor = json.loads(rollback_descriptor_json)
+                    
+                    # Execute rollback via actuator if available
+                    if actuator_registry:
+                        actuator = actuator_registry.get_actuator_for_lever(lever_id)
+                        if actuator:
+                            success = actuator.rollback(rollback_descriptor)
+                            if success:
+                                logger.info(f"Rolled back intervention {intervention_id}")
+                            else:
+                                logger.warning(f"Rollback failed for intervention {intervention_id}")
+                        else:
+                            logger.warning(f"No actuator found for lever {lever_id}")
+                    else:
+                        logger.info(f"Rollback descriptor for {intervention_id}: {rollback_descriptor}")
+                
+                rolled_back_ids.append(intervention_id)
+            except Exception as e:
+                logger.error(f"Error rolling back intervention {intervention_id}: {e}")
+        
+        # Record rollback in history
+        rollback_id = str(uuid.uuid4())
+        intervention_ids_json = json.dumps(rolled_back_ids)
+        created_at = datetime.now(timezone.utc).isoformat()
+        
+        cursor.execute("""
+            INSERT INTO rollback_history (rollback_id, epoch, n_steps, intervention_ids, created_at)
+            VALUES (?, ?, ?, ?, ?)
+        """, (rollback_id, epoch, n_steps, intervention_ids_json, created_at))
+        self.conn.commit()
+        
+        logger.info(f"Rolled back {len(rolled_back_ids)} interventions")
+        
+        return rolled_back_ids
+    
+    def restore_checkpoint(self, checkpoint_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Restore state from checkpoint.
+        
+        Args:
+            checkpoint_id: Checkpoint ID to restore
+            
+        Returns:
+            Dict[str, Any]: Restored state or None if not found
+        """
+        cursor = self.conn.cursor()
+        cursor.execute("""
+            SELECT state_json FROM checkpoints WHERE checkpoint_id = ?
+        """, (checkpoint_id,))
+        
+        row = cursor.fetchone()
+        if row:
+            state = json.loads(row[0])
+            logger.info(f"Restored checkpoint {checkpoint_id}")
+            return state
+        else:
+            logger.warning(f"Checkpoint {checkpoint_id} not found")
+            return None
+    
+    def get_latest_checkpoint(self, epoch: Optional[int] = None) -> Optional[str]:
+        """
+        Get the latest checkpoint ID.
+        
+        Args:
+            epoch: Optional epoch to filter by (get latest before or at this epoch)
+            
+        Returns:
+            str: Checkpoint ID or None
+        """
+        cursor = self.conn.cursor()
+        
+        if epoch is not None:
+            cursor.execute("""
+                SELECT checkpoint_id FROM checkpoints
+                WHERE epoch <= ?
+                ORDER BY created_at DESC
+                LIMIT 1
+            """, (epoch,))
+        else:
+            cursor.execute("""
+                SELECT checkpoint_id FROM checkpoints
+                ORDER BY created_at DESC
+                LIMIT 1
+            """)
+        
+        row = cursor.fetchone()
+        return row[0] if row else None
+    
+    def get_rollback_history(self, limit: int = 100) -> List[Dict[str, Any]]:
+        """
+        Get rollback history.
+        
+        Args:
+            limit: Maximum number of records to return
+            
+        Returns:
+            List[Dict[str, Any]]: Rollback history records
+        """
+        cursor = self.conn.cursor()
+        cursor.execute("""
+            SELECT rollback_id, epoch, n_steps, intervention_ids, created_at
+            FROM rollback_history
+            ORDER BY created_at DESC
+            LIMIT ?
+        """, (limit,))
+        
+        rows = cursor.fetchall()
+        return [
+            {
+                "rollback_id": row[0],
+                "epoch": row[1],
+                "n_steps": row[2],
+                "intervention_ids": json.loads(row[3]),
+                "created_at": row[4]
+            }
+            for row in rows
+        ]
+    
+    def _cleanup_old_checkpoints(self) -> None:
+        """Clean up checkpoints older than retention period."""
+        cutoff = datetime.now(timezone.utc).timestamp() - (self.retention_days * 86400)
+        cutoff_iso = datetime.fromtimestamp(cutoff, tz=timezone.utc).isoformat()
+        
+        cursor = self.conn.cursor()
+        cursor.execute("""
+            DELETE FROM checkpoints WHERE created_at < ?
+        """, (cutoff_iso,))
+        
+        deleted = cursor.rowcount
+        if deleted > 0:
+            logger.info(f"Cleaned up {deleted} old checkpoints")
+        
+        self.conn.commit()
+    
+    def close(self) -> None:
+        """Close database connection."""
+        self.conn.close()
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()
+