higpertext-cli 0.8.0__py3-none-any.whl

higpertext/kernel/domain/governance.py

@@ -0,0 +1,198 @@
+"""Entidades y Value Objects de Gobernanza (Dominio)."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum
+from datetime import date
+from typing import Optional
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"  # inmutable — no override posible
+    HIGH = "high"  # solo puede endurecerse
+    MEDIUM = "medium"  # solo puede endurecerse
+    LOW = "low"  # override bidireccional con justificación
+
+
+class Scope(str, Enum):
+    COMMIT = "commit"
+    PR = "pr"
+    DEPLOY = "deploy"
+    ANY = "any"  # aplica en todos los scopes
+
+
+@dataclass(frozen=True)
+class Rule:
+    """Unidad atómica de gobernanza.
+
+    Una regla es inmutable una vez creada. Los overrides de perfil
+    producen nuevas instancias de Rule, no modifican la original.
+    """
+
+    id: str
+    description: str
+    severity: Severity
+    scopes: tuple[Scope, ...]
+    automated: bool = False
+    capability: Optional[str] = None  # capability que valida esta regla
+    source: str = "global"  # "global" | nombre del perfil
+    numeric_threshold: Optional[float] = None  # para reglas cuantitativas
+
+    def applies_to(self, scope: Scope) -> bool:
+        return Scope.ANY in self.scopes or scope in self.scopes
+
+    def is_overridable_by(self, other_severity: Severity) -> bool:
+        """Una regla CRITICAL nunca es overridable. HIGH/MEDIUM solo pueden endurecerse."""
+        if self.severity == Severity.CRITICAL:
+            return False
+
+        severity_order = {
+            Severity.LOW: 1,
+            Severity.MEDIUM: 2,
+            Severity.HIGH: 3,
+            Severity.CRITICAL: 4,
+        }
+
+        return severity_order[other_severity] >= severity_order[self.severity]
+
+    def merge(self, override: "RuleOverride") -> "Rule":
+        """Produce una nueva Rule aplicando el override si es válido."""
+        if self.severity == Severity.CRITICAL:
+            return self  # CRITICAL no admite cambios
+
+        new_threshold = override.numeric_threshold
+        if self.severity in (Severity.HIGH, Severity.MEDIUM):
+            # Solo permite endurecer (threshold más alto = más estricto)
+            if (
+                self.numeric_threshold is not None
+                and new_threshold is not None
+                and new_threshold < self.numeric_threshold
+            ):
+                return self  # rechaza aflojar
+
+        return Rule(
+            id=self.id,
+            description=override.description or self.description,
+            severity=self.severity,
+            scopes=self.scopes,
+            automated=self.automated,
+            capability=self.capability,
+            source=override.source,
+            numeric_threshold=(
+                new_threshold if new_threshold is not None else self.numeric_threshold
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class RuleOverride:
+    """Instrucción de override desde governance.json de un perfil."""
+
+    rule_id: str
+    source: str
+    numeric_threshold: Optional[float] = None
+    description: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class GovernanceException:
+    """Excepción aprobada que suspende temporalmente una regla para un perfil."""
+
+    rule_id: str
+    reason: str
+    approver: str
+    profile: str
+    expires: Optional[date] = None
+    created_at: Optional[str] = None
+
+    def is_active(self) -> bool:
+        if self.expires is None:
+            return True
+        return date.today() <= self.expires
+
+    def to_dict(self) -> dict:
+        return {
+            "rule_id": self.rule_id,
+            "reason": self.reason,
+            "approver": self.approver,
+            "profile": self.profile,
+            "expires": self.expires.isoformat() if self.expires else None,
+            "created_at": self.created_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "GovernanceException":
+        expires_raw = data.get("expires")
+        expires = date.fromisoformat(expires_raw) if expires_raw else None
+        return cls(
+            rule_id=data["rule_id"],
+            reason=data.get("reason", ""),
+            approver=data.get("approver", "unknown"),
+            profile=data.get("profile", "global"),
+            expires=expires,
+            created_at=data.get("created_at"),
+        )
+
+
+class VerdictStatus(str, Enum):
+    PASSED = "passed"
+    WARN = "warn"
+    BLOCK = "block"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """Un hallazgo individual de una regla evaluada."""
+
+    rule_id: str
+    severity: Severity
+    message: str
+    source: str = "global"
+    detail: Optional[str] = None
+
+    @property
+    def blocks(self) -> bool:
+        return self.severity == Severity.CRITICAL
+
+
+@dataclass
+class Verdict:
+    """Resultado agregado de evaluar un conjunto de reglas."""
+
+    scope: str
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def status(self) -> VerdictStatus:
+        if any(f.blocks for f in self.findings):
+            return VerdictStatus.BLOCK
+        if self.findings:
+            return VerdictStatus.WARN
+        return VerdictStatus.PASSED
+
+    @property
+    def blocking_findings(self) -> list[Finding]:
+        return [f for f in self.findings if f.blocks]
+
+    @property
+    def warning_findings(self) -> list[Finding]:
+        return [f for f in self.findings if not f.blocks]
+
+    def add(self, finding: Finding) -> None:
+        self.findings.append(finding)
+
+    def to_dict(self) -> dict:
+        return {
+            "scope": self.scope,
+            "status": self.status.value,
+            "findings": [
+                {
+                    "rule_id": f.rule_id,
+                    "severity": f.severity.value,
+                    "message": f.message,
+                    "source": f.source,
+                    "detail": f.detail,
+                }
+                for f in self.findings
+            ],
+        }

higpertext/kernel/domain/hook_models.py

@@ -0,0 +1,29 @@
+"""Modelos de dominio para el sistema de hooks de higpertext."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+
+@dataclass
+class HookDefinition:
+    id: str
+    event: str
+    script: str  # ruta relativa al script Python
+    description: str = ""
+    matcher: str = ""  # filtro de herramienta, vacío = todas
+    timeout: int = 10
+    enabled: bool = True
+    assistants: list[str] = field(default_factory=list) 
+    profiles: list[str] = field(default_factory=list)  
+    capability_id: str = ""  # capability higpertext que origina este hook
+
+
+@dataclass
+class WebhookEvent:
+    id: str
+    event: str
+    url: str  # soporta ${ENV_VAR}
+    payload_template: dict = field(default_factory=dict)
+    assistants: list[str] = field(default_factory=list)
+    enabled: bool = False  # desactivado por defecto — requiere opt-in explícito
+    timeout: int = 5

higpertext/kernel/domain/profile_learner.py

@@ -0,0 +1,186 @@
+"""Profile Learner Domain layer — SessionPattern, SkillProfile, and scoring logic."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+
+@dataclass(frozen=True)
+class SessionPattern:
+    session_id: str
+    duration_min: float
+    commits: int
+    higpertext_adoption_pct: float
+    bash_direct_calls: int
+    capability_used_calls: int
+    hook_intercept_calls: int
+    higpertext_direct_calls: int
+    commit_types: tuple[str, ...] = field(default_factory=tuple)
+    commit_messages: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def is_effective(self) -> bool:
+        return self.duration_min <= 45 and self.commits >= 2
+
+    @property
+    def tool_calls_total(self) -> int:
+        return (
+            self.bash_direct_calls
+            + self.higpertext_direct_calls
+            + self.hook_intercept_calls
+            + self.capability_used_calls
+        )
+
+
+@dataclass
+class SkillProfile:
+    strong_patterns: list[str] = field(default_factory=list)
+    weak_patterns: list[str] = field(default_factory=list)
+    preferred_caps: list[str] = field(default_factory=list)
+    commit_topics: list[str] = field(default_factory=list)
+    cost_per_commit_avg: float = 0.0
+    higpertext_adoption_trend: float = 0.0
+    best_session_pattern: str = ""
+    total_sessions_analyzed: int = 0
+    last_updated: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat(timespec="seconds")
+    )
+
+    def to_dict(self) -> dict:
+        return {
+            "strong_patterns": self.strong_patterns,
+            "weak_patterns": self.weak_patterns,
+            "preferred_caps": self.preferred_caps,
+            "commit_topics": self.commit_topics,
+            "cost_per_commit_avg": self.cost_per_commit_avg,
+            "higpertext_adoption_trend": self.higpertext_adoption_trend,
+            "best_session_pattern": self.best_session_pattern,
+            "total_sessions_analyzed": self.total_sessions_analyzed,
+            "last_updated": self.last_updated,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> SkillProfile:
+        return cls(
+            strong_patterns=data.get("strong_patterns", []),
+            weak_patterns=data.get("weak_patterns", []),
+            preferred_caps=data.get("preferred_caps", []),
+            commit_topics=data.get("commit_topics", []),
+            cost_per_commit_avg=data.get("cost_per_commit_avg", 0.0),
+            higpertext_adoption_trend=data.get("higpertext_adoption_trend", 0.0),
+            best_session_pattern=data.get("best_session_pattern", ""),
+            total_sessions_analyzed=data.get("total_sessions_analyzed", 0),
+            last_updated=data.get("last_updated", ""),
+        )
+
+
+_PL_CONFIG_PATH = Path(__file__).resolve().parents[4] / "src" / "config" / "profile_learner.json"
+_PL_CFG: dict = json.loads(_PL_CONFIG_PATH.read_text(encoding="utf-8"))
+
+_CONVENTIONAL_TYPES = frozenset(_PL_CFG["conventional_commit_types"])
+_DEFAULTS: dict = dict(_PL_CFG["scoring_defaults"])
+
+
+def load_weights(project_root: Path | None = None) -> dict:
+    """Carga pesos desde scoring_weights.json; usa defaults si no existe."""
+    if project_root is None:
+        project_root = _resolve_root()
+    path = project_root / WORKSPACE_DIR_NAME / "config" / "scoring_weights.json"
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return {**_DEFAULTS, **{k: v for k, v in data.items() if not k.startswith("_")}}
+    except (OSError, json.JSONDecodeError):
+        return dict(_DEFAULTS)
+
+
+def save_weights(weights: dict, project_root: Path | None = None) -> None:
+    """Persiste pesos actualizados en scoring_weights.json."""
+    if project_root is None:
+        project_root = _resolve_root()
+    path = project_root / WORKSPACE_DIR_NAME / "config" / "scoring_weights.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    current: dict = {}
+    try:
+        current = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):  # nosec B110
+        pass
+    comment = current.get("_comment", "")
+    out = {"_comment": comment, **weights} if comment else dict(weights)
+    path.write_text(json.dumps(out, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def score_session(pattern: SessionPattern, weights: dict | None = None) -> float:
+    """Calcula score numérico para una sesión. Positivo = buena sesión."""
+    w = weights or load_weights()
+    score = 0.0
+
+    score += pattern.hook_intercept_calls * w["hook_intercept"]
+    score += pattern.capability_used_calls * w["capability_used"]
+    score += pattern.higpertext_direct_calls * w["higpertext_direct"]
+    score += pattern.bash_direct_calls * w["bash_direct_penalty"]
+
+    if pattern.commits == 0:
+        score += w["zero_commits_penalty"]
+
+    conventional_commits = sum(1 for t in pattern.commit_types if t in _CONVENTIONAL_TYPES)
+    score += conventional_commits * w["conventional_commit"]
+
+    if pattern.higpertext_adoption_pct >= w["high_adoption_threshold"]:
+        score += w["high_adoption_bonus"]
+
+    if (
+        pattern.duration_min <= w["effective_session_max_min"]
+        and pattern.commits >= w["effective_session_min_commits"]
+    ):
+        score += w["effective_session_bonus"]
+
+    return score
+
+
+def classify_patterns(
+    pattern: SessionPattern, weights: dict | None = None
+) -> tuple[list[str], list[str]]:
+    """Retorna (strong_patterns, weak_patterns) observados en la sesión."""
+    w = weights or load_weights()
+    strong: list[str] = []
+    weak: list[str] = []
+
+    if pattern.higpertext_adoption_pct >= w["high_adoption_threshold"]:
+        strong.append("alta adopción higpertext")
+    elif pattern.higpertext_adoption_pct < 40:
+        weak.append("baja adopción higpertext")
+
+    if (
+        pattern.duration_min <= w["effective_session_max_min"]
+        and pattern.commits >= w["effective_session_min_commits"]
+    ):
+        strong.append("sesiones cortas y productivas")
+
+    if pattern.commits >= 3:
+        strong.append("commits frecuentes")
+    elif pattern.commits == 0:
+        weak.append("sesiones sin commits")
+
+    if pattern.bash_direct_calls > 10:
+        weak.append(f"bash directo excesivo ({pattern.bash_direct_calls} llamadas)")
+
+    conventional = sum(1 for t in pattern.commit_types if t in _CONVENTIONAL_TYPES)
+    if conventional == len(pattern.commit_types) and pattern.commits > 0:
+        strong.append("commits convencionales correctos")
+
+    return strong, weak
+
+
+def _resolve_root() -> Path:
+    candidate = Path(__file__).resolve()
+    for _ in range(8):
+        if (candidate / "src/config/htx_config.json").exists():
+            return candidate
+        candidate = candidate.parent
+    _fallback = Path("/home/aomerge/Documentos/Proyects/agents/LLM-agent")
+    if (_fallback / "src/config/htx_config.json").exists():
+        return _fallback
+    return Path.cwd()

higpertext/kernel/domain/rag.py

@@ -0,0 +1,70 @@
+"""Semantic RAG Domain Entities and Interfaces (Domain Layer)."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from abc import ABC, abstractmethod
+
+
+@dataclass
+class DocumentChunk:
+    """Fragmento de documento o código fuente con metadatos asociados."""
+
+    file: str
+    content: str
+    chunk_type: str  # "class" | "function" | "markdown" | "general"
+    start_line: int
+    end_line: int
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class VectorEntry:
+    """Entrada que vincula un fragmento de texto con su vector de embedding."""
+
+    chunk: DocumentChunk
+    embedding: list[float]
+
+
+class IEmbeddingProvider(ABC):
+    """Interfaz para la generación de embeddings vectoriales."""
+
+    @abstractmethod
+    def get_embedding(self, text: str) -> list[float]:
+        """Calcula el vector de embedding para un texto dado."""
+        pass
+
+    @abstractmethod
+    def get_embeddings_batch(self, texts: list[str]) -> list[list[float]]:
+        """Calcula embeddings para una lista de textos en lote."""
+        pass
+
+
+class IVectorStore(ABC):
+    """Interfaz para persistencia y búsqueda por similitud de vectores."""
+
+    @abstractmethod
+    def add_entries(self, entries: list[VectorEntry]) -> None:
+        """Agrega un lote de entradas vectoriales al almacén."""
+        pass
+
+    @abstractmethod
+    def search(
+        self, query_vector: list[float], limit: int = 5
+    ) -> list[tuple[DocumentChunk, float]]:
+        """Busca los fragmentos más similares ordenados por score (similitud coseno)."""
+        pass
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Limpia todo el contenido del almacén."""
+        pass
+
+    @abstractmethod
+    def save(self) -> None:
+        """Persiste el estado actual de los vectores."""
+        pass
+
+    @abstractmethod
+    def load(self) -> None:
+        """Carga el estado de los vectores guardados."""
+        pass

higpertext/kernel/domain/repositories.py

@@ -0,0 +1,8 @@
+"""Compatibilidad legacy para puertos movidos a la capa de aplicación."""
+
+from higpertext.kernel.application.ports import (  # noqa: F401
+    ICapabilityRepository,
+    IProfileRepository,
+    ISessionRepository,
+    IWorkflowRepository,
+)

higpertext/kernel/domain/roadmap_reporter.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class PhaseStatus(str, Enum):
+    PENDING = "pending"
+    ACTIVE = "active"
+    DONE = "done"
+
+
+@dataclass(frozen=True)
+class Phase:
+    id: str
+    name: str
+    description: str
+    status: PhaseStatus
+    skills: list[str] = field(default_factory=list)
+    subagents: list[str] = field(default_factory=list)
+
+    @property
+    def is_done(self) -> bool:
+        return self.status == PhaseStatus.DONE
+
+    @property
+    def is_active(self) -> bool:
+        return self.status == PhaseStatus.ACTIVE
+
+
+@dataclass(frozen=True)
+class Roadmap:
+    id: str
+    name: str
+    description: str
+    phases: list[Phase] = field(default_factory=list)
+
+
+@dataclass
+class RoadmapReport:
+    roadmap: Roadmap
+
+    @property
+    def total_phases(self) -> int:
+        return len(self.roadmap.phases)
+
+    @property
+    def done_phases(self) -> int:
+        return sum(1 for p in self.roadmap.phases if p.is_done)
+
+    @property
+    def completion_pct(self) -> float:
+        if not self.roadmap.phases:
+            return 0.0
+        return round(self.done_phases / self.total_phases * 100, 2)
+
+    @property
+    def active_phase(self) -> Phase | None:
+        return next((p for p in self.roadmap.phases if p.is_active), None)
+
+    @property
+    def all_skills_used(self) -> list[str]:
+        seen: set[str] = set()
+        result = []
+        for p in self.roadmap.phases:
+            for s in p.skills:
+                if s not in seen:
+                    seen.add(s)
+                    result.append(s)
+        return result
+
+    @property
+    def all_subagents_used(self) -> list[str]:
+        seen: set[str] = set()
+        result = []
+        for p in self.roadmap.phases:
+            for a in p.subagents:
+                if a not in seen:
+                    seen.add(a)
+                    result.append(a)
+        return result

higpertext/kernel/domain/semantic_engine.py

@@ -0,0 +1,107 @@
+"""Semantic Engine Domain layer — Symbol, Relation, Cluster, and SemanticGraph."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum
+from collections import defaultdict
+
+
+class SymbolType(str, Enum):
+    CLASS = "class"
+    FUNCTION = "function"
+    METHOD = "method"
+    VARIABLE = "variable"
+    MODULE = "module"
+
+
+@dataclass(frozen=True)
+class Symbol:
+    name: str
+    type: SymbolType
+    file: str
+    line: int
+
+    @property
+    def fqn(self) -> str:
+        return f"{self.file}::{self.name}"
+
+    def __hash__(self) -> int:
+        return hash(self.fqn)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Symbol):
+            return NotImplemented
+        return self.fqn == other.fqn
+
+
+class RelationType(str, Enum):
+    CALLS = "calls"
+    IMPORTS = "imports"
+    INHERITS = "inherits"
+    USES = "uses"
+
+
+@dataclass(frozen=True)
+class Relation:
+    source: Symbol
+    target: Symbol
+    type: RelationType
+    confidence: float = field(default=1.0)
+
+    def __post_init__(self) -> None:
+        if not (0.0 <= self.confidence <= 1.0):
+            raise ValueError(f"confidence must be in [0, 1], got {self.confidence}")
+
+
+@dataclass(frozen=True)
+class Cluster:
+    id: str
+    members: tuple[Symbol, ...]
+
+    def __init__(self, id: str, members: list[Symbol]) -> None:
+        object.__setattr__(self, "id", id)
+        object.__setattr__(self, "members", tuple(members))
+
+    @property
+    def size(self) -> int:
+        return len(self.members)
+
+
+class SemanticGraph:
+    def __init__(self) -> None:
+        self._symbols: dict[str, Symbol] = {}
+        self._relations: list[Relation] = []
+        self._adjacency: dict[str, list[Symbol]] = defaultdict(list)
+        self._in_degree: dict[str, int] = defaultdict(int)
+
+    @property
+    def symbol_count(self) -> int:
+        return len(self._symbols)
+
+    @property
+    def relation_count(self) -> int:
+        return len(self._relations)
+
+    def add_symbol(self, symbol: Symbol) -> None:
+        self._symbols.setdefault(symbol.fqn, symbol)
+
+    def add_relation(self, relation: Relation) -> None:
+        self.add_symbol(relation.source)
+        self.add_symbol(relation.target)
+        self._relations.append(relation)
+        self._adjacency[relation.source.fqn].append(relation.target)
+        self._in_degree[relation.target.fqn] += 1
+
+    def neighbors(self, symbol: Symbol) -> list[Symbol]:
+        return list(self._adjacency.get(symbol.fqn, []))
+
+    def god_nodes(self, threshold: int = 5) -> list[Symbol]:
+        return [
+            self._symbols[fqn] for fqn, degree in self._in_degree.items() if degree >= threshold
+        ]
+
+    def all_symbols(self) -> list[Symbol]:
+        return list(self._symbols.values())
+
+    def all_relations(self) -> list[Relation]:
+        return list(self._relations)