higpertext-cli 0.8.0__py3-none-any.whl

higpertext/kernel/application/context_engine.py

@@ -0,0 +1,409 @@
+"""Context Engine Application layer — ContextAssembler, EfficiencyMeter, and TaskDecomposer."""
+
+from __future__ import annotations
+import json
+import re
+from pathlib import Path
+from higpertext.kernel.domain.context_engine import (
+    ContextPack,
+    FileSkeleton,
+    SymbolRef,
+    TaskIntent,
+    EfficiencyReport,
+    TaskNode,
+    TaskGraph,
+)
+
+from higpertext.kernel.infrastructure.context_engine import (
+    GraphIndex,
+    extract_skeleton,
+    should_skeletonize,
+    TelemetryReader,
+)
+
+# Ratios heurísticos de chars-por-token según tipo de contenido.
+_CHARS_PER_TOKEN: dict[str, float] = {
+    "markdown": 4.0,
+    "code": 3.5,
+    "skeleton": 5.0,
+}
+_MEMORY_FILE = Path(".memory/learnings.json")
+
+
+def iter_file_link_targets(markdown: str) -> list[str]:
+    """Extrae destinos `file://` de enlaces Markdown sin regex vulnerable a backtracking."""
+    targets: list[str] = []
+    cursor = 0
+    marker = "](file:///"
+    while True:
+        marker_index = markdown.find(marker, cursor)
+        if marker_index == -1:
+            return targets
+        label_start = markdown.rfind("[", 0, marker_index)
+        label = markdown[label_start + 1:marker_index] if label_start != -1 else ""
+        target_start = marker_index + len(marker)
+        target_end = markdown.find(")", target_start)
+        if target_end == -1:
+            return targets
+        if label.endswith(".py"):
+            targets.append(markdown[target_start:target_end])
+        cursor = target_end + 1
+
+
+class ContextAssembler:
+    """Orquesta la selección de símbolos relevantes bajo un presupuesto de tokens."""
+
+    def __init__(self, project_root: Path, graph_index: GraphIndex | None = None) -> None:
+        self.project_root = project_root
+        self._index = graph_index or GraphIndex(project_root)
+
+    def assemble(self, intent: TaskIntent) -> ContextPack:
+        """Construye un ContextPack con símbolos, esqueletos y memorias aplicables."""
+        candidates = self._index.search(list(intent.keywords))
+        ranked = self._rank(candidates, intent)
+        selected, skeletons = self._fit_to_budget(ranked, intent)
+        memories = self._fetch_memories(intent)
+        pack = ContextPack(
+            intent=intent,
+            relevant_symbols=selected,
+            applicable_memories=memories,
+            skeletons=skeletons,
+            estimated_tokens=0,
+        )
+        pack.estimated_tokens = self._estimate_tokens(pack)
+        return pack
+
+    def _rank(self, symbols: list[SymbolRef], intent: TaskIntent) -> list[SymbolRef]:
+        """Ordena por número de keywords que cada símbolo satisface (desc)."""
+        kws = [k.lower() for k in intent.keywords]
+
+        def score(s: SymbolRef) -> int:
+            haystack = f"{s.name} {s.file} {s.doc}".lower()
+            return sum(1 for k in kws if k in haystack)
+
+        return sorted(symbols, key=score, reverse=True)
+
+    def _fit_to_budget(
+        self, ranked: list[SymbolRef], intent: TaskIntent
+    ) -> tuple[list[SymbolRef], list[FileSkeleton]]:
+        """Agrega símbolos al pack; degrada a esqueleto si el archivo es grande."""
+        selected: list[SymbolRef] = []
+        skeletons: list[FileSkeleton] = []
+        seen_files: set[str] = set()
+
+        for sym in ranked:
+            trial = ContextPack(
+                intent=intent,
+                relevant_symbols=selected + [sym],
+                applicable_memories=[],
+                skeletons=skeletons,
+                estimated_tokens=0,
+            )
+            if self._estimate_tokens(trial) > intent.token_budget:
+                skeleton = self._try_skeletonize(sym.file, seen_files)
+                if skeleton:
+                    skeletons.append(skeleton)
+                continue
+            selected.append(sym)
+            seen_files.add(sym.file)
+
+        return selected, skeletons
+
+    def _try_skeletonize(self, filepath: str, seen: set[str]) -> FileSkeleton | None:
+        """Intenta crear un FileSkeleton si el archivo existe y no fue procesado ya."""
+        if filepath in seen:
+            return None
+        full_path = self.project_root / filepath
+        if not full_path.exists() or not filepath.endswith(".py"):
+            return None
+        source = full_path.read_text(encoding="utf-8")
+        if not should_skeletonize(source):
+            return None
+        seen.add(filepath)
+        return FileSkeleton(file=filepath, skeleton=extract_skeleton(source))
+
+    def _fetch_memories(self, intent: TaskIntent) -> list[str]:
+        """Busca en learnings.json entradas que coincidan léxica o semánticamente."""
+        memory_path = self.project_root / _MEMORY_FILE
+        if not memory_path.exists():
+            return []
+        try:
+            learnings: dict = json.loads(memory_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return []
+
+        # 1. Obtener matches léxicos tradicionales
+        matches = self._match_memories(learnings, intent.keywords)
+        
+        # 2. Obtener matches semánticos híbridos si hay API key y provider
+        try:
+            from higpertext.kernel.infrastructure.llm.providers.gemini_embeddings import GeminiEmbeddingProvider
+            from higpertext.kernel.infrastructure.database.local_vector_store import LocalVectorStore
+            
+            embedder = GeminiEmbeddingProvider(self.project_root)
+            query_str = " ".join(intent.keywords)
+            query_vec = embedder.get_embedding(query_str)
+            
+            # Recolectar todos los aprendizajes individuales
+            all_learnings = []
+            for tag, items in learnings.items():
+                for item in items:
+                    for learned_str in item.get("learned", []):
+                        if learned_str not in matches:
+                            all_learnings.append(learned_str)
+            
+            # Evaluar similitud semántica
+            semantic_candidates = []
+            for candidate in all_learnings:
+                try:
+                    cand_vec = embedder.get_embedding(candidate)
+                    score = LocalVectorStore._cosine_similarity(query_vec, cand_vec)
+                    if score >= 0.70:  # Umbral de similitud semántica mínima
+                        semantic_candidates.append((candidate, score))
+                except Exception:
+                    continue
+            
+            # Ordenar y tomar los mejores 3 matches semánticos adicionales
+            semantic_candidates.sort(key=lambda x: x[1], reverse=True)
+            for cand, _ in semantic_candidates[:3]:
+                matches.append(cand)
+        except Exception:
+            # Fallback explícito a coincidencia léxica pura si falla la red o API Key.
+            return list(set(matches))
+
+        return list(set(matches))
+
+    @staticmethod
+    def _match_memories(learnings: dict, keywords: tuple[str, ...]) -> list[str]:
+        """Filtra aprendizajes cuyas tags coincidan con al menos una keyword."""
+        kws = {k.lower() for k in keywords}
+        matches: list[str] = []
+        for tag, items in learnings.items():
+            if tag.lower() not in kws:
+                continue
+            for item in items:
+                matches.extend(item.get("learned", []))
+        return matches
+
+    @staticmethod
+    def _estimate_tokens(pack: ContextPack) -> int:
+        """Estima tokens usando ratios diferenciados por tipo de contenido."""
+        md = pack.to_markdown()
+        skeleton_chars = sum(len(sk.skeleton) for sk in pack.skeletons)
+        symbol_chars = sum(len(s.doc) + len(s.name) for s in pack.relevant_symbols)
+        memory_chars = sum(len(m) for m in pack.applicable_memories)
+        other_chars = len(md) - skeleton_chars - symbol_chars - memory_chars
+        tokens = (
+            max(other_chars, 0) / _CHARS_PER_TOKEN["markdown"]
+            + symbol_chars / _CHARS_PER_TOKEN["code"]
+            + skeleton_chars / _CHARS_PER_TOKEN["skeleton"]
+            + memory_chars / _CHARS_PER_TOKEN["markdown"]
+        )
+        return int(tokens)
+
+
+class EfficiencyMeter:
+    """Responsabilidad única: medir qué tan eficiente fue el uso del contexto en una sesión."""
+
+    def __init__(self, project_root: Path) -> None:
+        self.project_root = project_root
+        self._reader = TelemetryReader(project_root)
+
+    def measure_session(self, session_id: str) -> EfficiencyReport:
+        total_tokens = self._reader.total_tokens(session_id)
+        total_cost = self._reader.total_cost(session_id)
+        exploration = self._reader.exploration_reads(session_id)
+        higpertext_count = self._reader.higpertext_reads(session_id)
+        intercepts = self._reader.hook_intercepts(session_id)
+        files_read = self._reader.files_read(session_id)
+
+        total_reads = exploration + higpertext_count
+        waste_ratio = (exploration / total_reads) if total_reads > 0 else 0.0
+        hit_rate = self._compute_hit_rate(files_read)
+        peak_tokens, window_pct = self._read_window_peak()
+
+        return EfficiencyReport(
+            session_id=session_id,
+            total_tokens=total_tokens,
+            total_cost_usd=round(total_cost, 6),
+            exploration_reads=exploration,
+            higpertext_reads=higpertext_count,
+            hook_intercepts=intercepts,
+            context_hit_rate=round(hit_rate, 3),
+            exploration_waste_ratio=round(waste_ratio, 3),
+            window_usage_pct=round(window_pct, 3),
+            peak_window_tokens=peak_tokens,
+        )
+
+    def save_to_reports(self, report: EfficiencyReport) -> Path | None:
+        """Persiste el EfficiencyReport en .higpertext/reports/efficiency/ y actualiza el índice."""
+        try:
+            from higpertext.adapters.adapter_utils import save_report
+
+            return save_report(
+                target_dir=self.project_root,
+                report_id=f"context_engine.efficiency.{report.session_id}",
+                content=report.to_markdown(),
+                category="efficiency",
+            )
+        except Exception:
+            return None
+
+    def _read_window_peak(self) -> tuple[int, float]:
+        """Lee el pico de tokens de ventana desde window_state.json."""
+        try:
+            from higpertext.kernel.domain.context_engine import (
+                load_window_state,
+                _window_limit,
+            )
+
+            state = load_window_state(self.project_root)
+            limit = _window_limit()
+            return state.peak_tokens, state.usage_pct(limit)
+        except Exception:
+            return 0, 0.0
+
+    def _compute_hit_rate(self, files_read: set[str]) -> float:
+        """Calcula qué fracción de los archivos leídos estaba en algún context pack."""
+        from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+        if not files_read:
+            return 0.0
+        pack_dir = self.project_root / WORKSPACE_DIR_NAME / "state" / "context_packs"
+        if not pack_dir.exists():
+            return 0.0
+
+        covered: set[str] = set()
+        for pack_file in pack_dir.glob("*.md"):
+            try:
+                content = pack_file.read_text(encoding="utf-8")
+                covered.update(iter_file_link_targets(content))
+            except OSError:
+                continue
+
+        if not covered:
+            return 0.0
+
+        hits = sum(1 for f in files_read if any(f.endswith(c) or c.endswith(f) for c in covered))
+        return hits / len(files_read)
+
+
+# Heurísticas de skills por tipo de tarea
+_SKILLS_BY_TYPE = {
+    "refactor": ["clean-code", "ddd-standards"],
+    "feature": ["clean-code", "tdd-practices"],
+    "bugfix": ["clean-code", "best-practices"],
+    "review": ["best-practices", "ddd-standards"],
+}
+_SUBAGENTS_BY_TYPE = {
+    "refactor": ["code-auditor", "architect"],
+    "feature": ["architect", "test-engineer"],
+    "bugfix": ["code-auditor"],
+    "review": ["code-auditor"],
+}
+
+# Plantillas de fases por tipo de tarea.
+_TEMPLATES: dict[str, list[tuple[str, str, list[str]]]] = {
+    "refactor": [
+        ("explore", "Explorar el código existente y mapear el área de cambio", []),
+        (
+            "plan",
+            "Diseñar la nueva estructura y definir contratos de interfaces",
+            ["explore"],
+        ),
+        ("implement", "Implementar los cambios de refactorización", ["plan"]),
+        (
+            "test",
+            "Escribir y ejecutar tests que validen el comportamiento",
+            ["implement"],
+        ),
+        ("verify", "Verificar que no hay regresiones y la cobertura es ≥80%", ["test"]),
+    ],
+    "feature": [
+        (
+            "explore",
+            "Explorar el sistema existente para entender el punto de integración",
+            [],
+        ),
+        (
+            "spec",
+            "Definir la especificación y los casos de uso de la feature",
+            ["explore"],
+        ),
+        (
+            "tdd-red",
+            "Escribir tests que fallen (RED) para la nueva funcionalidad",
+            ["spec"],
+        ),
+        (
+            "implement",
+            "Implementar la feature hasta que los tests pasen (GREEN)",
+            ["tdd-red"],
+        ),
+        ("refactor", "Limpiar el código manteniendo los tests en verde", ["implement"]),
+    ],
+    "bugfix": [
+        ("reproduce", "Reproducir el bug y escribir un test que lo capture", []),
+        (
+            "diagnose",
+            "Identificar la causa raíz usando el semantic graph",
+            ["reproduce"],
+        ),
+        ("fix", "Aplicar el fix mínimo que pase el test de regresión", ["diagnose"]),
+        ("verify", "Verificar que el fix no introduce regresiones", ["fix"]),
+    ],
+    "review": [
+        ("explore", "Explorar los cambios del diff y su contexto en el repo", []),
+        ("quality", "Evaluar calidad, SOLID y Clean Code en los cambios", ["explore"]),
+        (
+            "security",
+            "Verificar que no hay vulnerabilidades ni secrets expuestos",
+            ["explore"],
+        ),
+        (
+            "summary",
+            "Producir el resumen de hallazgos con severidad",
+            ["quality", "security"],
+        ),
+    ],
+}
+_DEFAULT_TEMPLATE = _TEMPLATES["feature"]
+
+
+class TaskDecomposer:
+    """Genera un TaskGraph heurístico a partir de un TaskIntent."""
+
+    def __init__(self, project_root: Path) -> None:
+        self.project_root = project_root
+
+    def decompose(self, intent: TaskIntent) -> TaskGraph:
+        template = _TEMPLATES.get(intent.task_type, _DEFAULT_TEMPLATE)
+        skills = _SKILLS_BY_TYPE.get(intent.task_type, ["clean-code"])
+        subagents = _SUBAGENTS_BY_TYPE.get(intent.task_type, ["architect"])
+        prefix = _make_prefix(intent.goal)
+
+        nodes: list[TaskNode] = []
+        for suffix, description, dep_suffixes in template:
+            node_id = f"{prefix}-{suffix}"
+            depends_on = [f"{prefix}-{ds}" for ds in dep_suffixes]
+            nodes.append(
+                TaskNode(
+                    id=node_id,
+                    description=f"{description}: {_trim(intent.goal, 50)}",
+                    depends_on=depends_on,
+                    skills=list(skills),
+                    subagents=list(subagents),
+                )
+            )
+
+        return TaskGraph(nodes=nodes, goal=intent.goal)
+
+
+def _make_prefix(goal: str) -> str:
+    """Genera un slug corto y único para los IDs de nodos."""
+    words = re.findall(r"[\wáéíóúñ]{3,}", goal.lower())
+    slug = "-".join(words[:3])
+    return slug[:20] or "task"
+
+
+def _trim(text: str, max_len: int) -> str:
+    return text if len(text) <= max_len else text[:max_len] + "…"

higpertext/kernel/application/engine.py

@@ -0,0 +1,41 @@
+"""Nueva implementación limpia de HigpertextEngine (Aplicación)."""
+
+from __future__ import annotations
+from pathlib import Path
+from higpertext.kernel.application.profile_use_cases import (
+    GetAgentContextUseCase,
+    ValidateProfileUseCase,
+)
+from higpertext.kernel.infrastructure.file_repositories import (
+    FileProfileRepository,
+    FileCapabilityRepository,
+    FileWorkflowRepository,
+)
+from higpertext.kernel.pkg_resources import resolve_resource
+
+
+class ApplicationHigpertextEngine:
+    def __init__(self, base_dir: Path):
+        self.base_dir = base_dir
+        self.profiles_repo = FileProfileRepository(
+            resolve_resource(base_dir, "src", "config", "profiles")
+        )
+        self.caps_repo = FileCapabilityRepository(
+            resolve_resource(base_dir, "src", "higpertext", "capabilities")
+        )
+        self.wfs_repo = FileWorkflowRepository(resolve_resource(base_dir, "src", "workflows"))
+
+    def get_agent_context(self, profile_name: str, env_data: dict | None = None) -> dict:
+        return GetAgentContextUseCase(
+            self.profiles_repo,
+            self.caps_repo,
+            self.wfs_repo,
+            self.base_dir,
+        ).execute(profile_name, env_data)
+
+    def validate_profile(self, profile_name: str) -> tuple[bool, list[str], list[str]]:
+        return ValidateProfileUseCase(
+            self.profiles_repo,
+            self.caps_repo,
+            self.base_dir,
+        ).execute(profile_name)

higpertext/kernel/application/env_runtime.py

@@ -0,0 +1,174 @@
+"""Servicio principal para ejecutar entornos Docker/Podman locales (Aplicación)."""
+
+from __future__ import annotations
+import re
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from higpertext.kernel.domain.env_runtime import EnvironmentTemplate, RunSpec, RunState
+from higpertext.kernel.infrastructure.env_runtime import ComposeRenderer, resolve_backend, RunStore, TemplateLoader
+
+
+class EnvironmentService:
+    """Orquesta templates, compose, backends y estado de ejecuciones."""
+
+    def __init__(self, project_root: Path) -> None:
+        self.project_root = project_root
+        self.templates = TemplateLoader(project_root)
+        self.store = RunStore(project_root)
+        self.renderer = ComposeRenderer()
+
+    def catalog(self) -> list[EnvironmentTemplate]:
+        return self.templates.list_templates()
+
+    def run(self, spec: RunSpec) -> RunState:
+        template = self.templates.load(spec.template_id)
+        resolved = self._resolve_spec(template, spec)
+        backend = resolve_backend(resolved.engine)
+        run_id = self._new_run_id(template.id)
+        run_dir = self.store.run_dir(run_id)
+        compose_file = self.renderer.render(template, resolved, run_dir)
+        project_name = f"higpertext_{run_id}".replace("-", "_")
+        state = RunState(
+            run_id=run_id,
+            template_id=template.id,
+            engine=backend.engine,
+            status="running",
+            project_name=project_name,
+            run_dir=str(run_dir),
+            service=resolved.service,
+            command=resolved.command,
+        )
+        self.store.save(state)
+        up = backend.up(project_name, compose_file, self.project_root, resolved.timeout_seconds)
+        self._write_log(run_dir, "up.log", up.stdout, up.stderr)
+        if up.rc != 0:
+            return self._finish(state, "failed", up.rc, up.stderr or up.stdout)
+        if resolved.detach or not resolved.command:
+            state.summary = "Entorno iniciado en segundo plano."
+            self.store.save(state)
+            return state
+        result = backend.exec(
+            project_name,
+            compose_file,
+            self.project_root,
+            resolved.service,
+            resolved.command,
+            resolved.timeout_seconds,
+        )
+        self._write_log(run_dir, "command.log", result.stdout, result.stderr)
+        status = "success" if result.rc == 0 else "failed"
+        state = self._finish(
+            state,
+            status,
+            result.rc,
+            self._summarize_output(result.stdout, result.stderr),
+        )
+        if resolved.cleanup and not resolved.keep_alive:
+            down = backend.down(project_name, compose_file, self.project_root)
+            self._write_log(run_dir, "down.log", down.stdout, down.stderr)
+        return state
+
+    def status(self, run_id: str | None = None) -> list[RunState] | RunState:
+        return self.store.load(run_id) if run_id else self.store.list()
+
+    def logs(
+        self, run_id: str, service: str = "", tail: int = 200, errors_only: bool = False
+    ) -> str:
+        state = self.store.load(run_id)
+        compose_file = Path(state.run_dir) / "compose.yaml"
+        backend = resolve_backend(state.engine)
+        result = backend.logs(state.project_name, compose_file, self.project_root, service, tail)
+        text = result.stdout or result.stderr
+        if errors_only:
+            lines = [
+                line
+                for line in text.splitlines()
+                if re.search(r"error|failed|exception|traceback", line, re.I)
+            ]
+            return "\n".join(lines)
+        return text
+
+    def stop(self, run_id: str, volumes: bool = False) -> RunState:
+        state = self.store.load(run_id)
+        compose_file = Path(state.run_dir) / "compose.yaml"
+        backend = resolve_backend(state.engine)
+        result = backend.down(state.project_name, compose_file, self.project_root, volumes)
+        self._write_log(Path(state.run_dir), "stop.log", result.stdout, result.stderr)
+        return self._finish(
+            state,
+            "stopped" if result.rc == 0 else "failed",
+            result.rc,
+            result.stderr or result.stdout,
+        )
+
+    def clean(self, all_runs: bool = False) -> int:
+        states = self.store.list()
+        count = 0
+        for state in states:
+            if all_runs or state.status in {"success", "failed", "stopped"}:
+                self.store.delete(state.run_id)
+                count += 1
+        return count
+
+    def validate_template(self, template_id: str) -> EnvironmentTemplate:
+        return self.templates.load(template_id)
+
+    @staticmethod
+    def _resolve_spec(template: EnvironmentTemplate, spec: RunSpec) -> RunSpec:
+        task_name = spec.task or template.defaults.get("task", "")
+        task = template.tasks.get(task_name, {}) if task_name else {}
+        service = (
+            spec.service
+            or task.get("service")
+            or template.defaults.get("service")
+            or next(iter(template.services))
+        )
+        command = spec.command or task.get("command") or template.defaults.get("command", "")
+        timeout = spec.timeout_seconds or int(template.defaults.get("timeout_seconds", 300))
+        cleanup = (
+            spec.cleanup
+            if spec.cleanup is not None
+            else bool(template.defaults.get("cleanup", True))
+        )
+        return RunSpec(
+            template_id=spec.template_id,
+            engine=spec.engine,
+            task=task_name,
+            command=command,
+            service=service,
+            detach=spec.detach,
+            timeout_seconds=timeout,
+            keep_alive=spec.keep_alive,
+            cleanup=cleanup,
+            env=spec.env,
+        )
+
+    @staticmethod
+    def _new_run_id(template_id: str) -> str:
+        safe = re.sub(r"[^a-zA-Z0-9]+", "_", template_id).strip("_")[:24]
+        return f"env_{safe}_{uuid.uuid4().hex[:8]}"
+
+    def _finish(self, state: RunState, status: str, rc: int, summary: str) -> RunState:
+        state.status = status
+        state.exit_code = rc
+        state.finished_at = datetime.now(timezone.utc).isoformat()
+        state.summary = summary[:2000]
+        self.store.save(state)
+        return state
+
+    @staticmethod
+    def _write_log(run_dir: Path, name: str, stdout: str, stderr: str) -> None:
+        (run_dir / "logs" / name).write_text(
+            (stdout or "") + ("\n" + stderr if stderr else ""), encoding="utf-8"
+        )
+
+    @staticmethod
+    def _summarize_output(stdout: str, stderr: str) -> str:
+        text = stderr or stdout
+        lines = [line for line in text.splitlines() if line.strip()]
+        for line in lines:
+            if re.search(r"error|failed|exception|traceback|assert", line, re.I):
+                return line[:500]
+        return "\n".join(lines[-10:])[:1000]