hanuscode 1.0.0__py3-none-any.whl

hanus/context/manager.py

@@ -0,0 +1,837 @@
+# hanus/context/manager.py
+"""
+Gestor de contexto con compresión inteligente.
+
+Maneja conversaciones largas sin agotar el límite de tokens del modelo.
+Incluye:
+- Compresión con resúmenes jerárquicos
+- Índice de decisiones arquitectónicas persistentes
+- Compresión incremental
+- Metadatos de debugging
+"""
+from __future__ import annotations
+import time
+import json
+import hashlib
+from dataclasses import dataclass, field, asdict
+from typing import List, Dict, Tuple, Optional, Any, Set
+from pathlib import Path
+from datetime import datetime
+
+# Intentar usar tiktoken para conteo preciso, si no está disponible usar estimación
+try:
+    import tiktoken
+    HAS_TIKTOKEN = True
+except ImportError:
+    HAS_TIKTOKEN = False
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# DATA CLASSES
+# ─────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class CompressionStats:
+    """Estadísticas de compresión."""
+    original_tokens: int = 0
+    compressed_tokens: int = 0
+    messages_removed: int = 0
+    messages_summarized: int = 0
+    compression_ratio: float = 0.0
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+
+
+@dataclass
+class MessageImportance:
+    """Puntuación de importancia de un mensaje."""
+    index: int
+    role: str
+    score: float
+    reason: str = ""
+    tokens: int = 0
+
+
+@dataclass
+class ArchitectureDecision:
+    """Una decisión arquitectónica importante que nunca debe perderse."""
+    id: str
+    title: str
+    description: str
+    rationale: str
+    timestamp: str
+    files_involved: List[str] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+
+
+@dataclass
+class SectionSummary:
+    """Resumen de una sección de mensajes."""
+    start_index: int
+    end_index: int
+    message_count: int
+    original_tokens: int
+    summary_tokens: int
+    summary: str
+    topics: List[str] = field(default_factory=list)
+    files_mentioned: List[str] = field(default_factory=list)
+
+
+@dataclass
+class CompressionMetadata:
+    """Metadatos de una operación de compresión."""
+    compression_id: str
+    timestamp: str
+    strategy: str  # "hierarchical", "incremental", "aggressive"
+    stats: CompressionStats
+    sections_created: int = 0
+    decisions_preserved: int = 0
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CONTEXT MANAGER
+# ─────────────────────────────────────────────────────────────────────────────
+
+class ContextManager:
+    """
+    Gestiona el contexto de conversación con compresión inteligente.
+
+    Estrategias:
+    1. Token counting antes de API calls
+    2. Sliding window para mensajes antiguos
+    3. Hierarchical summarization de secciones
+    4. Importance scoring para retención
+    5. Architecture Decision Record (ADR) persistence
+
+    Uso:
+        manager = ContextManager(max_tokens=100000)
+        if manager.should_compress(messages):
+            messages, summary = manager.compress_with_summaries(messages)
+    """
+
+    # Límites por defecto
+    DEFAULT_MAX_TOKENS = 200000  # 200k tokens para modelos modernos
+    SUMMARY_THRESHOLD = 0.70     # Comprimir al 70% del límite
+    SAFETY_MARGIN = 0.90         # Nunca superar el 90% del límite del modelo
+    MIN_MESSAGES_TO_KEEP = 10
+    SYSTEM_MESSAGES_TO_KEEP = 3  # Siempre mantener los primeros N mensajes de sistema
+    SECTION_SIZE = 10            # Mensajes por sección para resúmenes jerárquicos
+
+    def __init__(
+        self,
+        max_tokens: int = DEFAULT_MAX_TOKENS,
+        preserve_recent: int = 20,
+        preserve_system: bool = True,
+        cache_dir: Optional[Path] = None,
+    ):
+        self.max_tokens = max_tokens
+        self.preserve_recent = preserve_recent
+        self.preserve_system = preserve_system
+        self._tokenizer = None
+
+        # Cache y persistencia
+        self.cache_dir = cache_dir or (Path.home() / ".hanus" / "context_cache")
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+        # Índice de decisiones arquitectónicas
+        self._architecture_decisions: List[ArchitectureDecision] = []
+        self._decisions_file = self.cache_dir / "architecture_decisions.json"
+        self._load_decisions()
+
+        # Resúmenes de secciones
+        self._section_summaries: List[SectionSummary] = []
+
+        # Metadatos de compresión
+        self._compression_history: List[CompressionMetadata] = []
+
+        # Inicializar tokenizer si está disponible
+        if HAS_TIKTOKEN:
+            try:
+                self._tokenizer = tiktoken.get_encoding("cl100k_base")
+            except Exception:
+                pass
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # API PÚBLICA
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def count_tokens(self, messages: List[Dict]) -> int:
+        """
+        Cuenta el total de tokens en el historial de mensajes.
+
+        Args:
+            messages: Lista de mensajes con 'role' y 'content'
+
+        Returns:
+            Número estimado de tokens
+        """
+        total = 0
+
+        for msg in messages:
+            content = str(msg.get("content", ""))
+
+            if self._tokenizer:
+                # Conteo preciso con tiktoken
+                total += len(self._tokenizer.encode(content))
+                # Overhead por mensaje (role, structure)
+                total += 4
+            else:
+                # Estimación: ~4 caracteres por token
+                total += len(content) // 4 + 1
+                # Overhead por mensaje
+                total += 10
+
+        return total
+
+    def should_compress(self, messages: List[Dict]) -> bool:
+        """
+        Determina si el contexto necesita compresión.
+
+        Args:
+            messages: Lista de mensajes actuales
+
+        Returns:
+            True si se debe comprimir
+        """
+        token_count = self.count_tokens(messages)
+        threshold = int(self.max_tokens * self.SUMMARY_THRESHOLD)
+        return token_count > threshold
+
+    def compress(self, messages: List[Dict]) -> Tuple[List[Dict], str]:
+        """
+        Comprime el historial de mensajes (método legacy, usa compress_with_summaries).
+
+        Args:
+            messages: Lista de mensajes actuales
+
+        Returns:
+            - Lista de mensajes comprimidos
+            - String con resumen de lo eliminado
+        """
+        return self.compress_with_summaries(messages)
+
+    def compress_with_summaries(
+        self,
+        messages: List[Dict],
+        strategy: str = "hierarchical"
+    ) -> Tuple[List[Dict], str]:
+        """
+        Comprime el historial con resúmenes jerárquicos por sección.
+
+        Estrategia:
+        1. Preservar mensajes del sistema
+        2. Preservar mensajes recientes
+        3. Crear resúmenes de secciones intermedias
+        4. Preservar decisiones arquitectónicas detectadas
+        5. Generar índice de temas y archivos
+
+        Args:
+            messages: Lista de mensajes actuales
+            strategy: "hierarchical", "incremental", o "aggressive"
+
+        Returns:
+            - Lista de mensajes comprimidos con resúmenes
+            - String con resumen de la compresión
+        """
+        stats = CompressionStats()
+        stats.original_tokens = self.count_tokens(messages)
+
+        if len(messages) <= self.MIN_MESSAGES_TO_KEEP:
+            return messages, ""
+
+        # Detectar y guardar decisiones arquitectónicas
+        self._detect_architecture_decisions(messages)
+
+        # Identificar mensajes a preservar
+        preserved_indices: Set[int] = set()
+
+        # 1. Preservar mensajes del sistema (primeros)
+        if self.preserve_system:
+            for i, msg in enumerate(messages):
+                if msg.get("role") == "system":
+                    preserved_indices.add(i)
+                else:
+                    break
+
+        # 2. Preservar mensajes recientes
+        recent_start = max(0, len(messages) - self.preserve_recent)
+        for i in range(recent_start, len(messages)):
+            preserved_indices.add(i)
+
+        # 3. Preservar mensajes con decisiones arquitectónicas
+        for decision in self._architecture_decisions:
+            for i, msg in enumerate(messages):
+                if decision.title.lower() in str(msg.get("content", "")).lower():
+                    preserved_indices.add(i)
+
+        # 4. Agrupar mensajes restantes en secciones y crear resúmenes
+        sections_to_summarize = self._create_sections(
+            messages,
+            preserved_indices,
+            section_size=self.SECTION_SIZE
+        )
+
+        # 5. Construir lista comprimida
+        compressed: List[Dict] = []
+        summary_parts: List[str] = []
+
+        # Añadir resumen de contexto previo si existe
+        if self._section_summaries:
+            context_summary = self._build_context_summary()
+            if context_summary:
+                compressed.append({
+                    "role": "system",
+                    "content": f"[Contexto previo comprimido]\n{context_summary}"
+                })
+
+        # Añadir resúmenes de secciones
+        for section in sections_to_summarize:
+            section_summary = self._summarize_section(messages, section)
+            if section_summary:
+                self._section_summaries.append(section_summary)
+                stats.messages_summarized += section.message_count
+
+                # Añadir mensaje de resumen
+                compressed.append({
+                    "role": "system",
+                    "content": f"[Resumen de {section.message_count} mensajes]\n{section_summary.summary}"
+                })
+
+        # Añadir mensajes preservados
+        for i, msg in enumerate(messages):
+            if i in preserved_indices:
+                compressed.append(msg)
+            else:
+                stats.messages_removed += 1
+
+        # 6. Guardar estadísticas
+        stats.compressed_tokens = self.count_tokens(compressed)
+        stats.compression_ratio = (
+            (stats.original_tokens - stats.compressed_tokens) / stats.original_tokens
+            if stats.original_tokens > 0 else 0
+        )
+
+        # 7. Crear metadatos
+        metadata = CompressionMetadata(
+            compression_id=hashlib.md5(str(time.time()).encode()).hexdigest()[:8],
+            timestamp=datetime.now().isoformat(),
+            strategy=strategy,
+            stats=stats,
+            sections_created=len(sections_to_summarize),
+            decisions_preserved=len([d for d in self._architecture_decisions])
+        )
+        self._compression_history.append(metadata)
+
+        # 8. Guardar decisiones actualizadas
+        self._save_decisions()
+
+        # 9. Crear resumen legible
+        summary = self._build_compression_summary(stats, metadata)
+
+        return compressed, summary
+
+    def incremental_compress(self, new_message: Dict, messages: List[Dict]) -> Tuple[bool, str]:
+        """
+        Compresión incremental: evalúa si un nuevo mensaje requiere compresión.
+
+        Más eficiente que compresión batch para conversaciones largas.
+
+        Args:
+            new_message: Nuevo mensaje a añadir
+            messages: Lista actual de mensajes
+
+        Returns:
+            - True si se realizó compresión
+            - Mensaje de estado
+        """
+        # Añadir mensaje temporalmente
+        test_messages = messages + [new_message]
+        current_tokens = self.count_tokens(test_messages)
+        threshold = int(self.max_tokens * self.SUMMARY_THRESHOLD)
+
+        if current_tokens <= threshold:
+            return False, "No se requiere compresión"
+
+        # Detectar si el nuevo mensaje contiene una decisión arquitectónica
+        content = str(new_message.get("content", ""))
+        if self._is_architecture_decision(content):
+            self._add_architecture_decision_from_message(new_message, len(messages))
+
+        # Compresión ligera: solo si estamos cerca del límite
+        if current_tokens > int(self.max_tokens * 0.85):
+            compressed, summary = self.compress_with_summaries(test_messages, strategy="incremental")
+            return True, f"Compresión incremental realizada: {summary}"
+
+        return False, "Dentro del umbral de seguridad"
+
+    def get_architecture_index(self) -> List[Dict]:
+        """
+        Retorna el índice de decisiones arquitectónicas.
+
+        Este índice nunca se pierde durante la compresión.
+        """
+        return [asdict(d) for d in self._architecture_decisions]
+
+    def add_architecture_decision(
+        self,
+        title: str,
+        description: str,
+        rationale: str,
+        files_involved: List[str] = None,
+        tags: List[str] = None
+    ) -> ArchitectureDecision:
+        """
+        Añade manualmente una decisión arquitectónica.
+
+        Args:
+            title: Título corto de la decisión
+            description: Descripción de la decisión
+            rationale: Por qué se tomó esta decisión
+            files_involved: Archivos relacionados
+            tags: Etiquetas para categorización
+
+        Returns:
+            La decisión creada
+        """
+        decision = ArchitectureDecision(
+            id=hashlib.md5(f"{title}{time.time()}".encode()).hexdigest()[:8],
+            title=title,
+            description=description,
+            rationale=rationale,
+            timestamp=datetime.now().isoformat(),
+            files_involved=files_involved or [],
+            tags=tags or []
+        )
+        self._architecture_decisions.append(decision)
+        self._save_decisions()
+        return decision
+
+    def get_context_stats(self, messages: List[Dict]) -> Dict[str, Any]:
+        """
+        Retorna estadísticas del contexto actual.
+
+        Args:
+            messages: Lista de mensajes
+
+        Returns:
+            Diccionario con estadísticas
+        """
+        total_tokens = self.count_tokens(messages)
+        threshold = int(self.max_tokens * self.SUMMARY_THRESHOLD)
+        safety_limit = int(self.max_tokens * self.SAFETY_MARGIN)
+
+        needs_compression = total_tokens > threshold or total_tokens > safety_limit
+
+        return {
+            "total_tokens": total_tokens,
+            "max_tokens": self.max_tokens,
+            "threshold_tokens": threshold,
+            "safety_limit": safety_limit,
+            "usage_percent": (total_tokens / self.max_tokens) * 100 if self.max_tokens > 0 else 0,
+            "message_count": len(messages),
+            "needs_compression": needs_compression,
+            "tokenizer": "tiktoken" if self._tokenizer else "estimate",
+            "architecture_decisions": len(self._architecture_decisions),
+            "section_summaries": len(self._section_summaries),
+            "compression_count": len(self._compression_history),
+        }
+
+    def get_sliding_window(
+        self,
+        messages: List[Dict],
+        max_tokens: Optional[int] = None
+    ) -> List[Dict]:
+        """
+        Obtiene una ventana deslizante de mensajes que cabe en el límite de tokens.
+
+        Args:
+            messages: Lista completa de mensajes
+            max_tokens: Límite de tokens (usa self.max_tokens si no se especifica)
+
+        Returns:
+            Lista de mensajes que caben en el límite
+        """
+        max_tokens = max_tokens or self.max_tokens
+
+        # Siempre incluir mensajes del sistema
+        system_messages = []
+        other_messages = []
+
+        for msg in messages:
+            if msg.get("role") == "system":
+                system_messages.append(msg)
+            else:
+                other_messages.append(msg)
+
+        # Calcular tokens del sistema
+        system_tokens = self.count_tokens(system_messages)
+        remaining_tokens = max_tokens - system_tokens
+
+        if remaining_tokens <= 0:
+            return system_messages
+
+        # Añadir mensajes desde el más reciente
+        result = list(system_messages)
+        current_tokens = system_tokens
+
+        for msg in reversed(other_messages):
+            msg_tokens = self._estimate_message_tokens(msg)
+            if current_tokens + msg_tokens <= max_tokens:
+                result.append(msg)
+                current_tokens += msg_tokens
+            else:
+                break
+
+        return result
+
+    def get_compression_history(self) -> List[Dict]:
+        """Retorna el historial de compresiones realizadas."""
+        return [asdict(m) for m in self._compression_history[-20:]]  # Últimas 20
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # MÉTODOS PRIVADOS
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _score_importance(self, msg: Dict, index: int, total: int) -> MessageImportance:
+        """
+        Puntúa la importancia de un mensaje (0-1).
+
+        Mensajes más importantes:
+        - Sistema (siempre 1.0)
+        - Errores y fallos
+        - Decisiones importantes
+        - Código clave
+        """
+        content = str(msg.get("content", ""))
+        role = msg.get("role", "")
+        score = 0.5  # Base
+        reasons = []
+
+        # Sistema siempre es importante
+        if role == "system":
+            return MessageImportance(
+                index=index,
+                role=role,
+                score=1.0,
+                reason="system message",
+                tokens=self._estimate_message_tokens(msg)
+            )
+
+        # Posición relativa (mensajes recientes son más importantes)
+        position_score = index / total
+        score += position_score * 0.2
+        reasons.append(f"position={position_score:.2f}")
+
+        # Contenido con errores es importante
+        error_keywords = ["error", "fail", "exception", "warning", "bug", "fix", "critical"]
+        if any(kw in content.lower() for kw in error_keywords):
+            score += 0.2
+            reasons.append("has_errors")
+
+        # Contenido con código es importante
+        if "```" in content or "def " in content or "class " in content:
+            score += 0.15
+            reasons.append("has_code")
+
+        # Contenido con rutas de archivo es importante
+        if "/" in content or ".py" in content or ".js" in content:
+            score += 0.1
+            reasons.append("has_paths")
+
+        # Mensajes con resultados de herramientas son importantes
+        if "[✓" in content or "[✗" in content or "Tool:" in content:
+            score += 0.15
+            reasons.append("tool_result")
+
+        # Decisiones arquitectónicas son MUY importantes
+        if self._is_architecture_decision(content):
+            score += 0.3
+            reasons.append("architecture_decision")
+
+        # Mensajes muy largos son menos importantes (probablemente outputs)
+        if len(content) > 5000:
+            score -= 0.1
+            reasons.append("very_long")
+
+        return MessageImportance(
+            index=index,
+            role=role,
+            score=min(1.0, max(0.0, score)),
+            reason=", ".join(reasons),
+            tokens=self._estimate_message_tokens(msg)
+        )
+
+    def _estimate_message_tokens(self, msg: Dict) -> int:
+        """Estima los tokens de un mensaje."""
+        content = str(msg.get("content", ""))
+        if self._tokenizer:
+            return len(self._tokenizer.encode(content)) + 4
+        return len(content) // 4 + 10
+
+    def _is_architecture_decision(self, content: str) -> bool:
+        """Detecta si un contenido contiene una decisión arquitectónica."""
+        decision_patterns = [
+            "decidí", "decidimos", "vamos a usar", "opté por",
+            "la arquitectura será", "el patrón será", "implementaremos con",
+            "we decided", "we will use", "the architecture", "the pattern",
+            "ADR:", "decision:", "architecture decision"
+        ]
+        content_lower = content.lower()
+        return any(pattern in content_lower for pattern in decision_patterns)
+
+    def _detect_architecture_decisions(self, messages: List[Dict]) -> None:
+        """Detecta y guarda decisiones arquitectónicas de los mensajes."""
+        for i, msg in enumerate(messages):
+            content = str(msg.get("content", ""))
+            if self._is_architecture_decision(content):
+                self._add_architecture_decision_from_message(msg, i)
+
+    def _add_architecture_decision_from_message(self, msg: Dict, index: int) -> None:
+        """Extrae y añade una decisión arquitectónica de un mensaje."""
+        content = str(msg.get("content", ""))
+
+        # Extraer título (primera línea relevante)
+        lines = content.split("\n")
+        title = "Decisión detectada"
+        for line in lines:
+            line = line.strip()
+            if line and not line.startswith("```") and len(line) > 10:
+                title = line[:80]
+                break
+
+        # Verificar que no existe ya
+        for existing in self._architecture_decisions:
+            if existing.title == title:
+                return
+
+        # Extraer archivos mencionados
+        import re
+        files = re.findall(r'[\w/.-]+\.(py|js|ts|java|go|rs|c|cpp|h)', content)
+
+        decision = ArchitectureDecision(
+            id=hashlib.md5(f"{title}{time.time()}".encode()).hexdigest()[:8],
+            title=title,
+            description=content[:500],
+            rationale="Detectado automáticamente del contexto",
+            timestamp=datetime.now().isoformat(),
+            files_involved=files[:10],
+            tags=["auto-detected"]
+        )
+        self._architecture_decisions.append(decision)
+
+    def _create_sections(
+        self,
+        messages: List[Dict],
+        preserved_indices: Set[int],
+        section_size: int = 10
+    ) -> List[SectionSummary]:
+        """
+        Crea secciones de mensajes para resumir.
+
+        Args:
+            messages: Lista de mensajes
+            preserved_indices: Índices que no se deben incluir en secciones
+            section_size: Tamaño máximo de cada sección
+
+        Returns:
+            Lista de resúmenes de sección
+        """
+        sections = []
+        current_section_start = None
+        current_section_end = None
+        current_tokens = 0
+
+        for i, msg in enumerate(messages):
+            if i in preserved_indices:
+                # Cerrar sección actual si existe
+                if current_section_start is not None:
+                    sections.append(SectionSummary(
+                        start_index=current_section_start,
+                        end_index=current_section_end,
+                        message_count=current_section_end - current_section_start + 1,
+                        original_tokens=current_tokens,
+                        summary_tokens=0,
+                        summary=""
+                    ))
+                    current_section_start = None
+                    current_section_end = None
+                    current_tokens = 0
+                continue
+
+            if current_section_start is None:
+                current_section_start = i
+
+            current_section_end = i
+            current_tokens += self._estimate_message_tokens(msg)
+
+            # Crear nueva sección si alcanzamos el tamaño
+            if (i - current_section_start + 1) >= section_size:
+                sections.append(SectionSummary(
+                    start_index=current_section_start,
+                    end_index=current_section_end,
+                    message_count=current_section_end - current_section_start + 1,
+                    original_tokens=current_tokens,
+                    summary_tokens=0,
+                    summary=""
+                ))
+                current_section_start = None
+                current_section_end = None
+                current_tokens = 0
+
+        # Cerrar última sección
+        if current_section_start is not None:
+            sections.append(SectionSummary(
+                start_index=current_section_start,
+                end_index=current_section_end,
+                message_count=current_section_end - current_section_start + 1,
+                original_tokens=current_tokens,
+                summary_tokens=0,
+                summary=""
+            ))
+
+        return sections
+
+    def _summarize_section(
+        self,
+        messages: List[Dict],
+        section: SectionSummary
+    ) -> Optional[SectionSummary]:
+        """
+        Genera un resumen de una sección de mensajes.
+
+        Args:
+            messages: Lista completa de mensajes
+            section: Sección a resumir
+
+        Returns:
+            Sección con resumen, o None si no se puede resumir
+        """
+        section_messages = messages[section.start_index:section.end_index + 1]
+
+        if not section_messages:
+            return None
+
+        # Extraer información clave
+        topics: Set[str] = set()
+        files: Set[str] = set()
+        user_questions: List[str] = []
+        assistant_actions: List[str] = []
+
+        import re
+
+        for msg in section_messages:
+            content = str(msg.get("content", ""))
+            role = msg.get("role", "")
+
+            # Extraer temas
+            words = re.findall(r'\b[A-Z][a-z]+\b', content)
+            topics.update(words[:5])
+
+            # Extraer archivos
+            file_matches = re.findall(r'[\w/.-]+\.(py|js|ts|java|go|rs|c|cpp|h|md|yaml|json)', content)
+            files.update(file_matches[:5])
+
+            if role == "user":
+                # Extraer pregunta principal
+                first_sentence = content.split(".")[0][:100]
+                if first_sentence:
+                    user_questions.append(first_sentence)
+            elif role == "assistant":
+                # Detectar acciones
+                if "write_file" in content or "edit_file" in content:
+                    assistant_actions.append("modificó archivos")
+                elif "exec_cmd" in content:
+                    assistant_actions.append("ejecutó comandos")
+                elif "grep_search" in content or "glob_search" in content:
+                    assistant_actions.append("buscó en código")
+
+        # Crear resumen
+        summary_parts = []
+
+        if user_questions:
+            summary_parts.append(f"Preguntas: {'; '.join(user_questions[:3])}")
+
+        if assistant_actions:
+            actions = list(set(assistant_actions))
+            summary_parts.append(f"Acciones: {', '.join(actions)}")
+
+        if files:
+            summary_parts.append(f"Archivos: {', '.join(list(files)[:5])}")
+
+        summary = "\n".join(summary_parts)
+
+        # Estimar tokens del resumen
+        summary_tokens = len(summary) // 4 + 10
+
+        return SectionSummary(
+            start_index=section.start_index,
+            end_index=section.end_index,
+            message_count=section.message_count,
+            original_tokens=section.original_tokens,
+            summary_tokens=summary_tokens,
+            summary=summary,
+            topics=list(topics)[:10],
+            files_mentioned=list(files)[:10]
+        )
+
+    def _build_context_summary(self) -> str:
+        """Construye un resumen del contexto previo a partir de secciones."""
+        if not self._section_summaries:
+            return ""
+
+        parts = ["## Resumen del contexto previo\n"]
+
+        for i, section in enumerate(self._section_summaries[-5:]):  # Últimas 5 secciones
+            if section.summary:
+                parts.append(f"### Sección {i + 1}")
+                parts.append(section.summary)
+                parts.append("")
+
+        # Añadir decisiones arquitectónicas
+        if self._architecture_decisions:
+            parts.append("### Decisiones arquitectónicas")
+            for decision in self._architecture_decisions[-5:]:
+                parts.append(f"- **{decision.title}**: {decision.description[:100]}...")
+            parts.append("")
+
+        return "\n".join(parts)
+
+    def _build_compression_summary(
+        self,
+        stats: CompressionStats,
+        metadata: CompressionMetadata
+    ) -> str:
+        """Construye un resumen legible de la compresión."""
+        lines = [
+            f"[Contexto comprimido - ID: {metadata.compression_id}]",
+            f"Strategy: {metadata.strategy}",
+            f"Tokens: {stats.original_tokens} → {stats.compressed_tokens} ({stats.compression_ratio:.1%} reducción)",
+            f"Mensajes: {stats.messages_removed} eliminados, {stats.messages_summarized} resumidos",
+            f"Secciones creadas: {metadata.sections_created}",
+            f"Decisiones preservadas: {metadata.decisions_preserved}",
+        ]
+        return "\n".join(lines)
+
+    def _load_decisions(self) -> None:
+        """Carga las decisiones arquitectónicas desde disco."""
+        if self._decisions_file.exists():
+            try:
+                data = json.loads(self._decisions_file.read_text(encoding="utf-8"))
+                self._architecture_decisions = [
+                    ArchitectureDecision(**d) for d in data.get("decisions", [])
+                ]
+            except Exception:
+                self._architecture_decisions = []
+
+    def _save_decisions(self) -> None:
+        """Guarda las decisiones arquitectónicas a disco."""
+        try:
+            data = {
+                "decisions": [asdict(d) for d in self._architecture_decisions],
+                "updated": datetime.now().isoformat()
+            }
+            self._decisions_file.write_text(
+                json.dumps(data, indent=2, ensure_ascii=False),
+                encoding="utf-8"
+            )
+        except Exception:
+            pass