skillpool 4.3.0__py3-none-any.whl

skillpool/resolver/models.py

@@ -0,0 +1,154 @@
+"""Resolver models — Pydantic schemas for skill resolution.
+
+Aligned with contracts/schemas/skill_resolve_request.v1.json
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class ResolveStrategy(StrEnum):
+    STRICT = "strict"
+    BEST_EFFORT = "best_effort"
+    FUZZY = "fuzzy"
+
+
+class ResolveStatus(StrEnum):
+    """Three-state resolution status (per schema)."""
+
+    RESOLVED = "resolved"
+    PARTIAL = "partial"
+    UNRESOLVED = "unresolved"
+
+
+class ConflictSeverity(StrEnum):
+    NONE = "none"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class ConflictType(StrEnum):
+    """Conflict type classification (per schema)."""
+
+    NAMESPACE_OVERLAP = "namespace_overlap"
+    SEMANTIC_CONFLICT = "semantic_conflict"
+    RESOURCE_CONTENTION = "resource_contention"
+    VERSION_MISMATCH = "version_mismatch"
+    SECURITY_POLICY = "security_policy"
+
+
+class DagEdgeType(StrEnum):
+    """Edge type classification (per schema)."""
+
+    DEPENDS_ON = "depends_on"
+    ENHANCES = "enhances"
+    CONFLICTS_WITH = "conflicts_with"
+    REPLACES = "replaces"
+
+
+class Domain(StrEnum):
+    """Task domain classification (per schema)."""
+
+    CODE_REFACTOR = "code_refactor"
+    SECURITY_FIX = "security_fix"
+    CODE_ANALYSIS = "code_analysis"
+    ARCHITECTURE_MIGRATION = "architecture_migration"
+    DOCUMENTATION = "documentation"
+    DEPENDENCY_UPGRADE = "dependency_upgrade"
+    TESTING = "testing"
+    DATA_MIGRATION = "data_migration"
+
+
+class DagEdge(BaseModel):
+    """Directed edge in the skill dependency graph."""
+
+    source: str = Field(description="Upstream skill ID (schema: 'from')")
+    target: str = Field(description="Downstream skill ID (schema: 'to')")
+    weight: float = Field(default=1.0, description="Edge weight (0-1)")
+    type: DagEdgeType = Field(default=DagEdgeType.DEPENDS_ON, description="Edge type")
+
+
+class ResolvedSkill(BaseModel):
+    """A single resolved skill with metadata."""
+
+    skill_id: str
+    name: str = ""
+    version: str = Field(default="1.0.0", description="Semantic version")
+    dimension: str = ""
+    domain: str = Field(default="", description="Task domain")
+    weight: float = 0.0
+    health_score: float = Field(default=1.0, ge=0.0, le=1.0)
+    trust_level: int = Field(default=3, ge=0, le=3)
+    dependencies: list[str] = Field(default_factory=list)
+    estimated_tokens: int = Field(default=0, description="Estimated token usage")
+    provides: list[str] = Field(default_factory=list, description="Capability tags this skill provides")
+    conflict: Optional[ConflictSeverity] = None
+
+
+class Conflict(BaseModel):
+    """Detected conflict between skills."""
+
+    skill_a: str
+    skill_b: str
+    jaccard_score: float = Field(default=0.0, ge=0.0, le=1.0)
+    severity: ConflictSeverity
+    conflict_type: ConflictType = Field(default=ConflictType.NAMESPACE_OVERLAP)
+    overlapping_namespaces: list[str] = Field(default_factory=list)
+    recommendation: str = Field(default="", description="Recommended resolution")
+
+
+class SkillResolveRequest(BaseModel):
+    """Request to resolve a skill chain.
+
+    Aligned with contracts/schemas/skill_resolve_request.v1.json:
+    - trace_id: W3C TraceContext (32 hex chars)
+    - task_description: Natural language task description
+    - domain: Task domain classification
+    - plan_id: Associated plan ID for audit
+    """
+
+    skill_ids: list[str] = Field(min_length=1, description="Root skill IDs to resolve (schema: available_skills)")
+    task_description: str = Field(default="", description="Natural language task description")
+    domain: Optional[Domain] = Field(default=None, description="Task domain classification")
+    trace_id: str = Field(default="", description="W3C TraceContext trace_id (32 hex chars)")
+    plan_id: str = Field(default="", description="Associated plan ID for audit tracing")
+    strategy: ResolveStrategy = ResolveStrategy.BEST_EFFORT
+    max_skills: int = Field(default=50, ge=1, le=200)
+    exclude_skills: list[str] = Field(default_factory=list)
+    require_independent: bool = False
+    min_health_score: float = Field(default=0.6, ge=0.0, le=1.0)
+    context: str = Field(default="", description="Resolution context for telemetry")
+
+
+class SkillResolveResponse(BaseModel):
+    """Response from skill resolution.
+
+    Aligned with contracts/schemas/skill_resolve_request.v1.json:
+    - status: three-state (resolved/partial/unresolved)
+    - health_scores: per-skill health score mapping
+    - feasibility_score: composite feasibility rating
+    """
+
+    resolved: list[ResolvedSkill] = Field(default_factory=list)
+    conflicts: list[Conflict] = Field(default_factory=list)
+    excluded: list[str] = Field(default_factory=list, description="Skills excluded by filters")
+    dag_edges: list[DagEdge] = Field(default_factory=list)
+    total_skills: int = 0
+    resolution_time_ms: float = 0.0
+    from_cache: bool = False
+    degraded: bool = False
+    error: Optional[str] = None
+    # Schema-aligned fields
+    status: ResolveStatus = Field(default=ResolveStatus.RESOLVED, description="Three-state resolution status")
+    health_scores: dict[str, float] = Field(
+        default_factory=dict, description="Per-skill health scores {skill_id: score}"
+    )
+    feasibility_score: float = Field(
+        default=1.0, ge=0.0, le=1.0, description="Composite feasibility = f(health_scores, conflicts)"
+    )

skillpool/resolver/rate_limiter.py

@@ -0,0 +1,48 @@
+"""RateLimiter — sliding window rate limiter."""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+
+
+class RateLimiter:
+    """Sliding window rate limiter.
+
+    Usage:
+        limiter = RateLimiter(max_requests=100, window_seconds=1.0)
+        if limiter.allow():
+            process_request()
+        else:
+            reject_with_429()
+    """
+
+    def __init__(self, max_requests: int = 100, window_seconds: float = 1.0) -> None:
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self._timestamps: deque[float] = deque()
+
+    def allow(self) -> bool:
+        """Check if a request is allowed under the rate limit."""
+        now = time.monotonic()
+        cutoff = now - self.window_seconds
+        # Remove expired timestamps
+        while self._timestamps and self._timestamps[0] <= cutoff:
+            self._timestamps.popleft()
+        if len(self._timestamps) < self.max_requests:
+            self._timestamps.append(now)
+            return True
+        return False
+
+    @property
+    def current_count(self) -> int:
+        """Number of requests in the current window."""
+        now = time.monotonic()
+        cutoff = now - self.window_seconds
+        while self._timestamps and self._timestamps[0] <= cutoff:
+            self._timestamps.popleft()
+        return len(self._timestamps)
+
+    def reset(self) -> None:
+        """Reset the rate limiter."""
+        self._timestamps.clear()

skillpool/resolver/skill_graph.py

@@ -0,0 +1,183 @@
+"""SkillGraph — DAG construction, topological sort, cycle detection, PPR ranking."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import scipy
+
+
+class CycleDetected(Exception):
+    """Raised when a cycle is detected in the skill dependency graph."""
+
+    def __init__(self, cycle_nodes: list[str]):
+        self.cycle_nodes = cycle_nodes
+        super().__init__(f"Cycle detected: {' → '.join(cycle_nodes)}")
+
+
+class SkillGraph:
+    """Directed Acyclic Graph for skill dependencies.
+
+    Supports topological sort, cycle detection, and PPR-based importance ranking.
+
+    Usage:
+        graph = SkillGraph()
+        graph.add_edge("S01", "S05a", weight=0.8)
+        order = graph.topological_sort()  # ["S01", "S05a"]
+        scores = graph.pagerank(["S01"])  # PPR importance scores
+    """
+
+    def __init__(self) -> None:
+        self._adj: dict[str, list[tuple[str, float]]] = defaultdict(list)
+        self._nodes: set[str] = set()
+        self._in_degree: dict[str, int] = defaultdict(int)
+
+    @property
+    def nodes(self) -> set[str]:
+        return set(self._nodes)
+
+    def add_node(self, node: str) -> None:
+        """Add a node without edges."""
+        self._nodes.add(node)
+        if node not in self._in_degree:
+            self._in_degree[node] = 0
+
+    def add_edge(self, source: str, target: str, weight: float = 1.0) -> None:
+        """Add a directed edge source → target."""
+        self.add_node(source)
+        self.add_node(target)
+        self._adj[source].append((target, weight))
+        self._in_degree[target] += 1
+
+    def get_edges(self) -> list[tuple[str, str, float]]:
+        """Return all edges as (source, target, weight) tuples."""
+        edges = []
+        for src, targets in self._adj.items():
+            for tgt, w in targets:
+                edges.append((src, tgt, w))
+        return edges
+
+    def get_dependencies(self, node: str) -> list[str]:
+        """Get nodes that `node` depends on (upstream)."""
+        deps = []
+        for src, targets in self._adj.items():
+            for tgt, _ in targets:
+                if tgt == node:
+                    deps.append(src)
+        return deps
+
+    def get_dependents(self, node: str) -> list[str]:
+        """Get nodes that depend on `node` (downstream)."""
+        return [tgt for tgt, _ in self._adj.get(node, [])]
+
+    def topological_sort(self) -> list[str]:
+        """Kahn's algorithm for topological sort. Raises CycleDetected if cycle exists."""
+        in_deg = dict(self._in_degree)
+        queue = [n for n in self._nodes if in_deg.get(n, 0) == 0]
+        result: list[str] = []
+
+        while queue:
+            node = queue.pop(0)
+            result.append(node)
+            for tgt, _ in self._adj.get(node, []):
+                in_deg[tgt] -= 1
+                if in_deg[tgt] == 0:
+                    queue.append(tgt)
+
+        if len(result) != len(self._nodes):
+            # Find cycle nodes
+            remaining = self._nodes - set(result)
+            raise CycleDetected(list(remaining))
+
+        return result
+
+    def has_cycle(self) -> bool:
+        """Check if the graph contains a cycle."""
+        try:
+            self.topological_sort()
+            return False
+        except CycleDetected:
+            return True
+
+    def subgraph(self, nodes: set[str]) -> SkillGraph:
+        """Extract a subgraph containing only the specified nodes."""
+        g = SkillGraph()
+        for node in nodes:
+            if node in self._nodes:
+                g.add_node(node)
+        for src, targets in self._adj.items():
+            if src in nodes:
+                for tgt, w in targets:
+                    if tgt in nodes:
+                        g.add_edge(src, tgt, w)
+        return g
+
+    def to_sparse_matrix(self) -> tuple["scipy.sparse.csr_matrix", dict[str, int]]:
+        """Convert graph to scipy sparse adjacency matrix.
+
+        Returns:
+            Tuple of (adjacency_matrix, node_to_index_mapping)
+
+        Raises:
+            ImportError if scipy/numpy not available
+        """
+        import numpy as np
+        from scipy import sparse as sp
+
+        node_list = sorted(self._nodes)
+        node_to_idx = {n: i for i, n in enumerate(node_list)}
+        n = len(node_list)
+
+        rows, cols, weights = [], [], []
+        for src, targets in self._adj.items():
+            for tgt, w in targets:
+                rows.append(node_to_idx[src])
+                cols.append(node_to_idx[tgt])
+                weights.append(w)
+
+        if rows:
+            adj = sp.csr_matrix(
+                (np.array(weights, dtype=np.float64), (rows, cols)),
+                shape=(n, n),
+            )
+        else:
+            adj = sp.csr_matrix((n, n))
+
+        return adj, node_to_idx
+
+    def pagerank(
+        self,
+        seeds: list[str],
+        alpha: float = 0.85,
+        method: str = "auto",
+    ) -> dict[str, float]:
+        """Compute Personalized PageRank scores for seed nodes.
+
+        Uses the 3-layer PPR implementation from skillpool.graph.ppr.
+
+        Args:
+            seeds: Seed skill IDs for personalization
+            alpha: Damping factor (default 0.85)
+            method: "python", "csr", "sknetwork", or "auto"
+
+        Returns:
+            Dict mapping skill_id → PPR score
+        """
+        from skillpool.graph.ppr import personalized_pagerank
+
+        adj, node_to_idx = self.to_sparse_matrix()
+
+        # Convert seed IDs to indices
+        seed_indices = [node_to_idx[s] for s in seeds if s in node_to_idx]
+        if not seed_indices:
+            # No valid seeds — return uniform scores
+            n = len(self._nodes)
+            return {node: 1.0 / n for node in self._nodes} if n > 0 else {}
+
+        scores_vec = personalized_pagerank(adj, seed_indices, alpha=alpha, method=method)
+
+        # Map back to skill IDs
+        idx_to_node = {i: n for n, i in node_to_idx.items()}
+        return {idx_to_node[i]: float(scores_vec[i]) for i in range(len(scores_vec))}

skillpool/review/__init__.py

@@ -0,0 +1,242 @@
+"""ReviewManager — orchestrates the multi-dimension review pipeline."""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+
+from skillpool.review.models import (
+    CheckpointLevel,
+    ReviewStatus,
+    ReviewTriggerRequest,
+    ReviewTriggerResponse,
+    SuspectSkill,
+    UpgradeRecommendation,
+)
+from skillpool.review.veto_evaluator import VetoEvaluator
+from skillpool.review.checkpoint_runner import CheckpointRunner
+from skillpool.review.suspect_marker import SuspectMarker
+from skillpool.review.async_queue import AsyncReviewQueue
+from skillpool.telemetry import TelemetryBridge
+
+logger = logging.getLogger(__name__)
+
+
+class ReviewManager:
+    """Orchestrates the full review pipeline.
+
+    Pipeline: validate request → check cooldown → run checkpoint →
+              evaluate veto → mark suspects → feed evolver → emit telemetry
+
+    When an EvolverLayer is provided, veto results feed into the defect
+    accumulation system, and evolution proposals are generated automatically.
+    """
+
+    def __init__(
+        self,
+        telemetry: TelemetryBridge | None = None,
+        checkpoint_runner: CheckpointRunner | None = None,
+        veto_evaluator: VetoEvaluator | None = None,
+        suspect_marker: SuspectMarker | None = None,
+        queue: AsyncReviewQueue | None = None,
+        evolver=None,
+    ) -> None:
+        self._telemetry = telemetry or TelemetryBridge()
+        self._runner = checkpoint_runner or CheckpointRunner()
+        self._evaluator = veto_evaluator or VetoEvaluator()
+        self._marker = suspect_marker or SuspectMarker()
+        self._queue = queue or AsyncReviewQueue()
+        self._evolver = evolver
+
+    def trigger(self, request: ReviewTriggerRequest) -> ReviewTriggerResponse:
+        """Execute the full review pipeline for a trigger request."""
+        start_ms = time.time() * 1000
+
+        # Step 1: Check cooldown via queue (returns the review_id)
+        try:
+            review_id = self._queue.submit(request)
+        except ValueError:
+            # Cooldown violation — return queued status
+            return ReviewTriggerResponse(
+                review_id=uuid.uuid4().hex[:16],
+                status=ReviewStatus.QUEUED,
+                checkpoint=request.checkpoint,
+                scores={},
+                veto_triggered=False,
+                veto_details=[],
+                suspect_skills=[],
+                recommendation=UpgradeRecommendation.NONE,
+                duration_ms=round(time.time() * 1000 - start_ms, 2),
+            )
+        except RuntimeError:
+            # Max concurrent reached — return queued
+            return ReviewTriggerResponse(
+                review_id=uuid.uuid4().hex[:16],
+                status=ReviewStatus.QUEUED,
+                checkpoint=request.checkpoint,
+                scores={},
+                veto_triggered=False,
+                veto_details=[],
+                suspect_skills=[],
+                recommendation=UpgradeRecommendation.NONE,
+                duration_ms=round(time.time() * 1000 - start_ms, 2),
+            )
+
+        # Mark as processing
+        self._queue.set_status(review_id, ReviewStatus.PROCESSING)
+
+        # Step 2: Run checkpoint
+        try:
+            scores = self._runner.run_checkpoint(
+                level=request.checkpoint,
+                skills=request.affected_skills,
+            )
+        except Exception as e:
+            logger.error("Checkpoint run failed for review %s: %s", review_id, e)
+            self._queue.set_status(review_id, ReviewStatus.FAILED)
+            return ReviewTriggerResponse(
+                review_id=review_id,
+                status=ReviewStatus.FAILED,
+                checkpoint=request.checkpoint,
+                scores={},
+                veto_triggered=False,
+                veto_details=[],
+                suspect_skills=[],
+                recommendation=UpgradeRecommendation.NONE,
+                duration_ms=round(time.time() * 1000 - start_ms, 2),
+            )
+
+        # Step 3: Evaluate veto (only for L2, L3, L4)
+        veto_details = []
+        veto_triggered = False
+        if request.checkpoint in (CheckpointLevel.L2, CheckpointLevel.L3, CheckpointLevel.L4):
+            veto_details, veto_triggered = self._evaluator.evaluate(scores)
+
+        # Step 4: Mark suspect skills
+        suspect_skills: list[SuspectSkill] = []
+        for detail in veto_details:
+            if detail.blocks:
+                for skill_id in request.affected_skills:
+                    self._marker.mark(
+                        skill_id=skill_id,
+                        reason=f"Veto {detail.rule.value}: {detail.recommendation}",
+                        suspected_dimension=detail.dimension,
+                    )
+        suspect_skills = self._marker.list_suspects()
+
+        # Step 5: Feed evolver (if available) and determine recommendation
+        recommendation = self._determine_recommendation(veto_details)
+        self._feed_evolver(veto_details, request, recommendation)
+
+        # Step 6: Determine final status
+        if veto_triggered:
+            status = ReviewStatus.PARTIAL
+        else:
+            status = ReviewStatus.COMPLETED
+
+        self._queue.set_status(review_id, status)
+
+        # Step 7: Emit telemetry (propagate trace_id from request)
+        for skill_id in request.affected_skills:
+            self._telemetry.emit(
+                event_type="review_completed",
+                skill_id=skill_id,
+                payload={
+                    "review_id": review_id,
+                    "checkpoint": request.checkpoint.value,
+                    "trigger": request.trigger.value,
+                    "veto_triggered": veto_triggered,
+                    "recommendation": recommendation.value,
+                    "scores": scores,
+                },
+                trace_id=request.trace_id,
+            )
+
+        duration_ms = round(time.time() * 1000 - start_ms, 2)
+        return ReviewTriggerResponse(
+            review_id=review_id,
+            status=status,
+            checkpoint=request.checkpoint,
+            scores=scores,
+            veto_triggered=veto_triggered,
+            veto_details=veto_details,
+            suspect_skills=suspect_skills,
+            recommendation=recommendation,
+            duration_ms=duration_ms,
+        )
+
+    @staticmethod
+    def _determine_recommendation(veto_details: list) -> UpgradeRecommendation:
+        """Determine upgrade recommendation from veto results.
+
+        - MAJOR: any P0-level veto (V1 security block)
+        - MINOR: any P1-level veto (V2, V3, V4)
+        - PATCH: only V5 risk notice or V6 explanation
+        - NONE: no vetoes at all
+        """
+        if not veto_details:
+            return UpgradeRecommendation.NONE
+
+        blocking = [d for d in veto_details if d.blocks]
+        if not blocking:
+            # Only non-blocking (V5) → PATCH
+            return UpgradeRecommendation.PATCH
+
+        # Check for MAJOR triggers (security = V1)
+        for d in blocking:
+            if d.rule.value in ("V1",):
+                return UpgradeRecommendation.MAJOR
+
+        # Check for MINOR triggers (V2, V3, V4)
+        for d in blocking:
+            if d.rule.value in ("V2", "V3", "V4"):
+                return UpgradeRecommendation.MINOR
+
+        # V6 only → PATCH
+        return UpgradeRecommendation.PATCH
+
+    def _feed_evolver(self, veto_details, request, recommendation) -> None:
+        """Feed veto results into EvolverLayer for defect accumulation.
+
+        When evolver is available, each blocking veto is recorded as a defect.
+        Non-blocking vetoes are recorded as MINOR defects for tracking.
+        Evolution proposals are created when defect thresholds are reached.
+        """
+        if self._evolver is None:
+            return
+
+        from skillpool.evolver import DefectSeverity
+
+        for detail in veto_details:
+            # Map veto severity to defect severity
+            if detail.blocks:
+                if detail.rule.value == "V1":
+                    severity = DefectSeverity.CRITICAL
+                else:
+                    severity = DefectSeverity.MAJOR
+            else:
+                severity = DefectSeverity.MINOR
+
+            # Record one defect per affected skill per veto
+            for skill_id in request.affected_skills:
+                self._evolver.record_defect(
+                    skill_id=skill_id,
+                    version="current",
+                    severity=severity,
+                    description=f"Veto {detail.rule.value}: {detail.recommendation}",
+                )
+
+        # If recommendation is MAJOR/MINOR, create an evolution proposal
+        if recommendation in (UpgradeRecommendation.MAJOR, UpgradeRecommendation.MINOR):
+            context = {
+                "trigger": "review_veto",
+                "recommendation": recommendation.value,
+                "checkpoint": request.checkpoint.value,
+                "affected_skills": request.affected_skills,
+                "veto_count": len(veto_details),
+            }
+            self._evolver.create_proposal(
+                context=context,
+                risk="high" if recommendation == UpgradeRecommendation.MAJOR else "medium",
+            )