higpertext-cli 0.8.0__py3-none-any.whl

higpertext/kernel/application/ports.py

@@ -0,0 +1,49 @@
+"""Puertos de aplicación para persistencia y carga de recursos del kernel."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from higpertext.kernel.domain.entities import Capability, Profile, Session, Workflow
+
+
+class IProfileRepository(ABC):
+    @abstractmethod
+    def load(self, name: str) -> Profile:
+        """Carga un perfil por su nombre."""
+
+    @abstractmethod
+    def list_all(self) -> list[str]:
+        """Lista los nombres de todos los perfiles disponibles."""
+
+
+class ICapabilityRepository(ABC):
+    @abstractmethod
+    def load(self, cap_id: str) -> Capability:
+        """Carga una capacidad por su ID."""
+
+    @abstractmethod
+    def list_all(self) -> list[Capability]:
+        """Lista todas las capacidades disponibles."""
+
+
+class IWorkflowRepository(ABC):
+    @abstractmethod
+    def list_all(self) -> list[Workflow]:
+        """Lista todos los workflows disponibles."""
+
+
+class ISessionRepository(ABC):
+    @abstractmethod
+    def load_active(self) -> Session | None:
+        """Carga la sesión activa si existe."""
+
+    @abstractmethod
+    def save(self, session: Session) -> None:
+        """Guarda el estado de la sesión."""
+
+    @abstractmethod
+    def delete(self) -> None:
+        """Elimina el estado de la sesión activa."""

higpertext/kernel/application/profile_learner.py

@@ -0,0 +1,358 @@
+"""Profile Learner Application layer — ProfileExtractor, ProfileUpdater, and WeightsCalibrator."""
+
+from __future__ import annotations
+import math
+import re
+from collections import Counter
+from pathlib import Path
+from higpertext.kernel.domain.profile_learner import (
+    SessionPattern,
+    SkillProfile,
+    classify_patterns,
+    load_weights,
+    save_weights,
+    score_session,
+)
+
+
+class ProfileExtractor:
+    """Lee eventos de telemetría y extrae patrones de comportamiento del usuario."""
+
+    def __init__(self, project_root: Path) -> None:
+        self._root = project_root
+
+    def extract(self, days: int = 30) -> tuple[SkillProfile, list[SessionPattern]]:
+        from higpertext.kernel.application.telemetry import TelemetryAggregator
+
+        agg = TelemetryAggregator(self._root)
+        metrics = agg.compute(days)
+        if not metrics:
+            return SkillProfile(), []
+
+        events = agg.load(days)
+        patterns = self._build_patterns(events, metrics)
+        return self._build_profile(patterns, metrics), patterns
+
+    def _build_patterns(self, events: list[dict], metrics: dict) -> list[SessionPattern]:
+        from collections import defaultdict
+
+        sessions: dict[str, dict] = defaultdict(
+            lambda: {
+                "duration_min": 0.0,
+                "commits": [],
+                "caps": [],
+                "intercepts": [],
+                "higpertext_direct": 0,
+                "bash_direct": 0,
+                "adoption_pct": 0.0,
+            }
+        )
+
+        for e in events:
+            sid = e.get("session_id", "unknown")
+            ev = e.get("event", "")
+            if ev == "session_stop":
+                sessions[sid]["duration_min"] = e.get("duration_min", 0.0)
+            elif ev == "commit":
+                sessions[sid]["commits"].append(e)
+            elif ev == "capability_used":
+                sessions[sid]["caps"].append(e.get("capability", ""))
+            elif ev == "hook_intercept":
+                sessions[sid]["intercepts"].append(e.get("capability", ""))
+            elif ev == "tool_call":
+                if e.get("is_higpertext_call"):
+                    sessions[sid]["higpertext_direct"] += 1
+                else:
+                    sessions[sid]["bash_direct"] += 1
+
+        patterns = []
+        for sid, s in sessions.items():
+            higpertext_count = len(s["caps"]) + len(s["intercepts"]) + s["higpertext_direct"]
+            bash = s["bash_direct"]
+            total = higpertext_count + bash
+            adoption = round(higpertext_count / total * 100, 1) if total else 0.0
+
+            commit_types = tuple(_parse_commit_type(c.get("type", "")) for c in s["commits"])
+            commit_messages = tuple(c.get("scope", "") for c in s["commits"] if c.get("scope"))
+
+            patterns.append(
+                SessionPattern(
+                    session_id=sid,
+                    duration_min=s["duration_min"],
+                    commits=len(s["commits"]),
+                    higpertext_adoption_pct=adoption,
+                    bash_direct_calls=bash,
+                    capability_used_calls=len(s["caps"]),
+                    hook_intercept_calls=len(s["intercepts"]),
+                    higpertext_direct_calls=s["higpertext_direct"],
+                    commit_types=commit_types,
+                    commit_messages=commit_messages,
+                )
+            )
+        return patterns
+
+    def _build_profile(self, patterns: list[SessionPattern], metrics: dict) -> SkillProfile:
+        if not patterns:
+            return SkillProfile()
+
+        all_strong: Counter = Counter()
+        all_weak: Counter = Counter()
+        cap_counter: Counter = Counter()
+
+        for p in patterns:
+            strong, weak = classify_patterns(p)
+            for s in strong:
+                all_strong[s] += 1
+            for w in weak:
+                all_weak[w] += 1
+            cap_counter.update(p.commit_messages)
+
+        all_messages = [m for p in patterns for m in p.commit_messages]
+        topics = extract_commit_topics(all_messages, top_n=5)
+
+        corr = metrics.get("correlations", {})
+        avg_adoption = sum(p.higpertext_adoption_pct for p in patterns) / len(patterns)
+
+        effective = [p for p in patterns if p.is_effective]
+        best = (
+            f"sesiones <45min con ≥2 commits ({len(effective)} de {len(patterns)})"
+            if effective
+            else "sin patrón efectivo identificado aún"
+        )
+
+        return SkillProfile(
+            strong_patterns=[k for k, _ in all_strong.most_common(5)],
+            weak_patterns=[k for k, _ in all_weak.most_common(5)],
+            preferred_caps=[cap for cap, _ in cap_counter.most_common(5)],
+            commit_topics=topics,
+            cost_per_commit_avg=corr.get("cost_per_commit_usd", 0.0),
+            higpertext_adoption_trend=round(avg_adoption, 1),
+            best_session_pattern=best,
+            total_sessions_analyzed=len(patterns),
+        )
+
+
+_DECAY = 0.8  # peso del perfil histórico vs. nuevo batch
+
+
+class ProfileUpdater:
+    """Combina perfil existente con nuevo batch. Sesiones recientes pesan más."""
+
+    def merge(self, existing: SkillProfile | None, fresh: SkillProfile) -> SkillProfile:
+        if existing is None:
+            return fresh
+
+        return SkillProfile(
+            strong_patterns=_merge_lists(existing.strong_patterns, fresh.strong_patterns),
+            weak_patterns=_merge_lists(existing.weak_patterns, fresh.weak_patterns),
+            preferred_caps=_merge_lists(existing.preferred_caps, fresh.preferred_caps),
+            commit_topics=_merge_lists(existing.commit_topics, fresh.commit_topics),
+            cost_per_commit_avg=_decay_float(
+                existing.cost_per_commit_avg, fresh.cost_per_commit_avg
+            ),
+            higpertext_adoption_trend=_decay_float(
+                existing.higpertext_adoption_trend, fresh.higpertext_adoption_trend
+            ),
+            best_session_pattern=fresh.best_session_pattern or existing.best_session_pattern,
+            total_sessions_analyzed=(
+                existing.total_sessions_analyzed + fresh.total_sessions_analyzed
+            ),
+        )
+
+
+def _decay_float(old: float, new: float) -> float:
+    return round(old * _DECAY + new * (1 - _DECAY), 4)
+
+
+def _merge_lists(old: list[str], new: list[str]) -> list[str]:
+    """Une listas priorizando los del batch nuevo, sin duplicados."""
+    seen: set[str] = set()
+    result: list[str] = []
+    for item in new + old:
+        if item not in seen:
+            seen.add(item)
+            result.append(item)
+    return result[:5]
+
+
+_MIN_SESSIONS_ZSCORE = 10
+_MIN_SESSIONS_REGRESSION = 20
+_LEARNING_RATE = 0.01
+_EPOCHS = 500
+
+
+class WeightsCalibrator:
+    """Ajusta pesos de scoring usando el historial de SessionPatterns.
+
+    - < 10 sesiones : solo carga pesos existentes (sin cambios)
+    - >= 10 sesiones: calibración z-score (normaliza distribución de scores)
+    - >= 20 sesiones: regresión lineal (optimiza predicción de productividad)
+    """
+
+    def __init__(self, project_root: Path) -> None:
+        self._root = project_root
+
+    def calibrate(self, patterns: list[SessionPattern]) -> dict:
+        n = len(patterns)
+        weights = load_weights(self._root)
+
+        if n < _MIN_SESSIONS_ZSCORE:
+            return weights
+
+        if n >= _MIN_SESSIONS_REGRESSION:
+            weights = self._regression_calibrate(patterns, weights)
+        else:
+            weights = self._zscore_calibrate(patterns, weights)
+
+        save_weights(weights, self._root)
+        return weights
+
+    def _zscore_calibrate(self, patterns: list[SessionPattern], weights: dict) -> dict:
+        """Ajusta el multiplicador global para que el score promedio sea 0."""
+        scores = [score_session(p, weights) for p in patterns]
+        mean = sum(scores) / len(scores)
+        variance = sum((s - mean) ** 2 for s in scores) / len(scores)
+        std = math.sqrt(variance) if variance > 0 else 1.0
+
+        # Escala todos los pesos numéricos para que std ≈ 10 (rango legible)
+        target_std = 10.0
+        if std < 0.01:
+            return weights
+        scale = target_std / std
+
+        calibrated = dict(weights)
+        _SCALE_KEYS = {
+            "hook_intercept",
+            "capability_used",
+            "higpertext_direct",
+            "bash_direct_penalty",
+            "zero_commits_penalty",
+            "conventional_commit",
+            "high_adoption_bonus",
+            "effective_session_bonus",
+        }
+        for key in _SCALE_KEYS:
+            if key in calibrated and isinstance(calibrated[key], (int, float)):
+                calibrated[key] = round(calibrated[key] * scale, 4)
+
+        return calibrated
+
+    def _regression_calibrate(self, patterns: list[SessionPattern], weights: dict) -> dict:
+        """Aprende pesos que mejor predicen commits_per_session (proxy de productividad)."""
+        features, targets = _build_feature_matrix(patterns)
+        if not features:
+            return weights
+
+        n_features = len(features[0])
+        w = [1.0] * n_features  # pesos iniciales uniformes
+        n = len(features)
+
+        for _ in range(_EPOCHS):
+            grad = [0.0] * n_features
+            for x, y in zip(features, targets):
+                pred = sum(wi * xi for wi, xi in zip(w, x))
+                err = pred - y
+                for j in range(n_features):
+                    grad[j] += (2 / n) * err * x[j]
+            w = [wi - _LEARNING_RATE * g for wi, g in zip(w, grad)]
+
+        calibrated = dict(weights)
+        _REGRESSION_KEYS = [
+            "hook_intercept",
+            "capability_used",
+            "higpertext_direct",
+            "bash_direct_penalty",
+            "conventional_commit",
+        ]
+        for i, key in enumerate(_REGRESSION_KEYS):
+            if i < len(w) and key in calibrated:
+                calibrated[key] = round(w[i], 4)
+
+        return calibrated
+
+
+def _build_feature_matrix(
+    patterns: list[SessionPattern],
+) -> tuple[list[list[float]], list[float]]:
+    """Construye matriz de features y vector de targets para regresión lineal simple.
+
+    Features por sesión (normalización básica):
+        0: hook_intercept_count  / 10
+        1: capability_count      / 10
+        2: higpertext_pct        (0-1)
+        3: duration_min          / 60
+    Target: commits_per_session (proxy de productividad)
+    """
+    features: list[list[float]] = []
+    targets: list[float] = []
+
+    for p in patterns:
+        total_tools = (p.higpertext_direct_calls or 0) + (p.bash_direct_calls or 0) + 1
+        higpertext_pct = (p.higpertext_direct_calls or 0) / total_tools
+
+        feat = [
+            (p.hook_intercept_calls or 0) / 10.0,
+            (p.capability_used_calls or 0) / 10.0,
+            higpertext_pct,
+            (p.duration_min or 0.0) / 60.0,
+        ]
+        features.append(feat)
+        targets.append(float(p.commits or 0))
+
+    return features, targets
+
+
+def extract_commit_topics(messages: list[str], top_n: int = 5) -> list[str]:
+    """Extrae temas recurrentes usando TF-IDF simplificado (sin dependencias externas)."""
+    if not messages:
+        return []
+
+    docs = [_tokenize(m) for m in messages]
+    n_docs = len(docs)
+
+    tf: list[Counter] = [Counter(d) for d in docs]
+    df: Counter = Counter()
+    for doc in docs:
+        df.update(set(doc))
+
+    import math
+
+    scores: Counter = Counter()
+    for doc_tf in tf:
+        total = sum(doc_tf.values()) or 1
+        for term, count in doc_tf.items():
+            tfidf = (count / total) * math.log((n_docs + 1) / (df[term] + 1))
+            scores[term] += tfidf
+
+    return [term for term, _ in scores.most_common(top_n)]
+
+
+def _tokenize(text: str) -> list[str]:
+    tokens = re.findall(r"[a-zA-Z_][a-zA-Z0-9_]{2,}", text.lower())
+    stopwords = {
+        "the",
+        "and",
+        "for",
+        "fix",
+        "add",
+        "update",
+        "feat",
+        "chore",
+        "refactor",
+        "test",
+        "docs",
+        "style",
+        "perf",
+        "build",
+        "this",
+        "with",
+        "from",
+        "that",
+        "into",
+        "when",
+    }
+    return [t for t in tokens if t not in stopwords]
+
+
+def _parse_commit_type(raw: str) -> str:
+    return raw.split("(")[0].strip().lower() if raw else "unknown"

higpertext/kernel/application/profile_service.py

@@ -0,0 +1,205 @@
+"""Servicio de Aplicación para resolución, validación y gestión de perfiles (DDD)."""
+
+from __future__ import annotations
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+import json
+import os
+from dataclasses import asdict
+from pathlib import Path
+from higpertext.kernel.application.ports import (
+    IProfileRepository,
+    ICapabilityRepository,
+)
+from higpertext.kernel.domain.entities import Profile
+from higpertext.kernel.pkg_resources import resolve_resource
+
+
+class ProfileApplicationService:
+    def __init__(self, profile_repo: IProfileRepository):
+        self.profile_repo = profile_repo
+
+    def get_profile_data(self, name: str) -> dict:
+        profile = self.profile_repo.load(name)
+        return asdict(profile)
+
+    def get_all_profile_names(self) -> list[str]:
+        return self.profile_repo.list_all()
+
+
+class ProfileManager:
+    """Facade que conecta FileProfileRepository + ProfileApplicationService."""
+
+    def __init__(self, profiles_dir: Path):
+        self.profiles_dir = profiles_dir
+        from higpertext.kernel.infrastructure.file_repositories import FileProfileRepository
+
+        self._repo = FileProfileRepository(profiles_dir)
+        self._service = ProfileApplicationService(self._repo)
+
+    def _get_custom_profiles_dir(self) -> Path:
+        return Path(os.getcwd()).resolve() / WORKSPACE_DIR_NAME / "profiles"
+
+    def _get_all_profile_files(self) -> list[Path]:
+        files = list(self.profiles_dir.glob("*.json"))
+        custom_dir = self._get_custom_profiles_dir()
+        if custom_dir.exists():
+            files.extend(custom_dir.glob("*.json"))
+        return files
+
+    def load_profile(self, profile_name: str) -> dict:
+        return self._service.get_profile_data(profile_name)
+
+    def list_profiles(self) -> list[str]:
+        return self._service.get_all_profile_names()
+
+
+class ProfileService:
+    def __init__(
+        self,
+        profiles_repo: IProfileRepository,
+        caps_repo: ICapabilityRepository,
+        base_dir: Path,
+    ):
+        self.profiles_repo = profiles_repo
+        self.caps_repo = caps_repo
+        self.base_dir = base_dir
+
+    def resolve_hierarchy(self, profile_name: str, visited: set[str] | None = None) -> Profile:
+        """Resuelve recursivamente la herencia de un perfil mezclando sus campos."""
+        if visited is None:
+            visited = set()
+
+        name_lower = profile_name.lower()
+        if name_lower in visited:
+            cycle = " -> ".join(list(visited) + [profile_name])
+            raise ValueError(f"Herencia cíclica detectada en los perfiles: {cycle}")
+
+        visited.add(name_lower)
+        profile = self.profiles_repo.load(profile_name)
+
+        if not profile.extends:
+            return profile
+
+        parent = self.resolve_hierarchy(profile.extends, visited)
+
+        merged_caps = self._merge_lists(parent.capabilities, profile.capabilities)
+        merged_skills = self._merge_lists(parent.session_skills, profile.session_skills)
+        merged_subagents = self._merge_lists(parent.session_subagents, profile.session_subagents)
+
+        system_prompt = (
+            profile.system_prompt if profile.system_prompt.strip() else parent.system_prompt
+        )
+
+        return Profile(
+            name=profile.name,
+            description=profile.description or parent.description,
+            system_prompt=system_prompt,
+            capabilities=merged_caps,
+            session_skills=merged_skills,
+            session_subagents=merged_subagents,
+            governance_access=profile.governance_access or parent.governance_access,
+            extends=profile.extends,
+            model=profile.model or parent.model,
+        )
+
+    def _merge_lists(self, parent_list: list[str], child_list: list[str]) -> list[str]:
+        merged = list(parent_list)
+        for item in child_list:
+            if item not in merged:
+                merged.append(item)
+        return merged
+
+    def validate_profile(self, profile_name: str) -> tuple[bool, list[str], list[str]]:
+        """Valida la estructura, integridad, dependencias y saturación de contexto de un perfil."""
+        errors = []
+        warnings = []
+        try:
+            resolved = self.resolve_hierarchy(profile_name)
+        except (FileNotFoundError, ValueError) as e:
+            return False, [str(e)], []
+
+        self._validate_capabilities(resolved.capabilities, errors)
+
+        total_chars = len(resolved.system_prompt)
+        total_chars += self._validate_skills(resolved.session_skills, errors)
+        total_chars += self._validate_subagents(resolved.session_subagents, errors)
+
+        self._validate_context_saturation(total_chars, warnings)
+
+        return len(errors) == 0, errors, warnings
+
+    def _validate_capabilities(self, capabilities: list[str], errors: list[str]) -> None:
+        for cap_id in capabilities:
+            try:
+                self.caps_repo.load(cap_id)
+            except FileNotFoundError:
+                errors.append(f"Capacidad '{cap_id}' referenciada no encontrada en el repositorio.")
+
+    def _validate_skills(self, skills: list[str], errors: list[str]) -> int:
+        total_chars = 0
+        skills_dirs = self._resolve_template_dirs("skills")
+        for skill in skills:
+            matches = self._find_in_dirs(skills_dirs, f"{skill}.json")
+            if not matches:
+                errors.append(
+                    f"Skill '{skill}' referenciada no tiene plantilla en templates/skills."
+                )
+            else:
+                try:
+                    s_data = json.loads(matches[0].read_text(encoding="utf-8"))
+                    total_chars += len(s_data.get("content", ""))
+                except Exception:  # nosec B110
+                    pass
+        return total_chars
+
+    def _validate_subagents(self, subagents: list[str], errors: list[str]) -> int:
+        total_chars = 0
+        subagents_dirs = self._resolve_template_dirs("subagents")
+        for subagent in subagents:
+            matches = self._find_in_dirs(subagents_dirs, f"{subagent}.json")
+            if not matches:
+                errors.append(
+                    f"Subagent '{subagent}' referenciado no tiene"
+                    " plantilla en templates/subagents."
+                )
+            else:
+                try:
+                    total_chars += len(matches[0].read_text(encoding="utf-8"))
+                except Exception:  # nosec B110
+                    pass
+        return total_chars
+
+    def _validate_context_saturation(self, total_chars: int, warnings: list[str]) -> None:
+        if total_chars > 50000:
+            warnings.append(
+                f"Saturación crítica de contexto: El tamaño estimado"
+                f" del perfil ({total_chars} chars) "
+                "es demasiado alto y degradará el rendimiento del LLM."
+            )
+        elif total_chars > 25000:
+            warnings.append(
+                f"Riesgo de saturación de contexto: El tamaño estimado"
+                f" del perfil ({total_chars} chars) "
+                "es alto y podría diluir la atención del LLM."
+            )
+
+    def _resolve_template_dirs(self, subdir: str) -> list[Path]:
+        """Retorna lista de directorios de templates: core primero, luego agente externo."""
+        dirs = [resolve_resource(self.base_dir, "src", "higpertext", "templates", subdir)]
+        agent_templates = self.base_dir / WORKSPACE_DIR_NAME / "agent_templates" / subdir
+        if agent_templates.exists():
+            dirs.append(agent_templates)
+        return dirs
+
+    def _find_in_dirs(self, dirs: list[Path], filename: str) -> list[Path]:
+        """Busca filename (o skill.json en subdirectorio homónimo) en múltiples directorios."""
+        matches: list[Path] = []
+        stem = Path(filename).stem  # e.g. "clean-code"
+        for d in dirs:
+            if not d.exists():
+                continue
+            matches.extend(d.rglob(filename))
+            subdir_skill = d / stem / "skill.json"
+            if subdir_skill.exists():
+                matches.append(subdir_skill)
+        return matches

higpertext/kernel/application/profile_services.py

@@ -0,0 +1,6 @@
+"""Re-export de compatibilidad — ver profile_service.py."""
+
+from higpertext.kernel.application.profile_service import (  # noqa: F401
+    ProfileApplicationService,
+    ProfileManager,
+)