skillpool 4.3.0__py3-none-any.whl

skillpool/resolver/__init__.py

@@ -0,0 +1,320 @@
+"""SkillResolver — skill chain resolution engine."""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Optional
+
+from skillpool.resolver.models import (
+    Conflict,
+    ConflictSeverity,
+    ConflictType as ConflictType,
+    DagEdge,
+    DagEdgeType,
+    Domain as Domain,
+    ResolveStatus,
+    ResolveStrategy as ResolveStrategy,
+    ResolvedSkill,
+    SkillResolveRequest,
+    SkillResolveResponse,
+)
+from skillpool.resolver.skill_graph import CycleDetected, SkillGraph
+from skillpool.resolver.conflict_detector import ConflictDetector
+from skillpool.resolver.health_filter import HealthFilter
+from skillpool.resolver.cache import LRUCache
+from skillpool.resolver.circuit_breaker import CircuitBreaker, CircuitState
+from skillpool.resolver.rate_limiter import RateLimiter
+
+
+# Simulated skill registry for resolver (production: backed by Registry)
+_SKILL_REGISTRY: dict[str, dict] = {}
+_REGISTRY_LOCK = threading.Lock()
+
+
+def register_skill(skill_id: str, data: dict) -> None:
+    """Register a skill in the resolver's local registry."""
+    with _REGISTRY_LOCK:
+        _SKILL_REGISTRY[skill_id] = data
+
+
+def clear_registry() -> None:
+    """Clear the resolver's local registry."""
+    with _REGISTRY_LOCK:
+        _SKILL_REGISTRY.clear()
+
+
+class SkillResolver:
+    """Resolve skill chains from CSDF definitions.
+
+    Pipeline:
+    1. Fetch skills from registry
+    2. Build dependency DAG
+    3. Cycle detection
+    4. Conflict detection (Jaccard)
+    5. Health filter
+    6. Topological sort
+    7. Apply constraints (max_skills, exclude, require_independent)
+    8. Return resolved chain
+
+    When a Registry is provided, skill metadata and lifecycle state are
+    sourced from the Registry instead of the in-memory dict. The Registry
+    provides proper 9-state lifecycle governance, supply chain evidence
+    verification, and persistent storage.
+
+    Usage:
+        resolver = SkillResolver()
+        response = resolver.resolve(SkillResolveRequest(skill_ids=["S01", "S05a"]))
+    """
+
+    def __init__(
+        self,
+        skill_registry: Optional[dict[str, dict]] = None,
+        cache_max_size: int = 128,
+        cache_ttl: float = 3600.0,
+        circuit_failure_threshold: int = 5,
+        circuit_recovery_timeout: float = 30.0,
+        rate_max_requests: int = 100,
+        rate_window_seconds: float = 1.0,
+        conflict_threshold: float = 0.5,
+        min_health_score: float = 0.6,
+        registry=None,
+    ) -> None:
+        self._registry_store = skill_registry if skill_registry is not None else _SKILL_REGISTRY
+        self._cache = LRUCache(max_size=cache_max_size, ttl_seconds=cache_ttl)
+        self._circuit = CircuitBreaker(
+            failure_threshold=circuit_failure_threshold,
+            recovery_timeout=circuit_recovery_timeout,
+        )
+        self._limiter = RateLimiter(
+            max_requests=rate_max_requests,
+            window_seconds=rate_window_seconds,
+        )
+        self._conflict_threshold = conflict_threshold
+        self._min_health_score = min_health_score
+        self._registry = registry
+
+    @property
+    def circuit_state(self) -> CircuitState:
+        return self._circuit.state
+
+    def resolve(self, request: SkillResolveRequest) -> SkillResolveResponse:
+        """Resolve a skill chain from the request."""
+        start = time.monotonic()
+
+        # Rate limit check
+        if not self._limiter.allow():
+            return SkillResolveResponse(
+                error="rate_limit_exceeded",
+                degraded=True,
+                resolution_time_ms=(time.monotonic() - start) * 1000,
+            )
+
+        # Circuit breaker check
+        if not self._circuit.allow_request():
+            return SkillResolveResponse(
+                degraded=True,
+                error="circuit_open",
+                resolution_time_ms=(time.monotonic() - start) * 1000,
+            )
+
+        # Cache check
+        cache_key = LRUCache.make_key(
+            request.skill_ids,
+            strategy=request.strategy.value,
+            max_skills=request.max_skills,
+            exclude=request.exclude_skills,
+        )
+        cached = self._cache.get(cache_key)
+        if cached is not None:
+            cached.from_cache = True
+            cached.resolution_time_ms = (time.monotonic() - start) * 1000
+            return cached
+
+        # Resolve
+        try:
+            response = self._do_resolve(request)
+            self._circuit.record_success()
+        except CycleDetected as e:
+            self._circuit.record_failure()
+            return SkillResolveResponse(
+                error=str(e),
+                resolution_time_ms=(time.monotonic() - start) * 1000,
+            )
+        except Exception as e:
+            self._circuit.record_failure()
+            return SkillResolveResponse(
+                error=str(e),
+                degraded=True,
+                resolution_time_ms=(time.monotonic() - start) * 1000,
+            )
+
+        # Cache result
+        self._cache.put(cache_key, response)
+        response.resolution_time_ms = (time.monotonic() - start) * 1000
+        return response
+
+    def _do_resolve(self, request: SkillResolveRequest) -> SkillResolveResponse:
+        """Core resolution logic."""
+        # 1. Fetch skills
+        fetched = self._fetch_skills(request.skill_ids)
+        if not fetched:
+            return SkillResolveResponse(
+                error="no_skills_found",
+                status=ResolveStatus.UNRESOLVED,
+            )
+
+        # 2. Build DAG
+        graph = self._build_dag(fetched)
+
+        # 3. Cycle detection
+        graph.topological_sort()  # raises CycleDetected
+
+        # 4. Conflict detection
+        conflict_detector = ConflictDetector(threshold=self._conflict_threshold)
+        for sid, sdata in fetched.items():
+            conflict_detector.register(
+                skill_id=sid,
+                name=sdata.get("name", ""),
+                dimension=sdata.get("dimension", ""),
+                namespaces=sdata.get("namespaces", []),
+            )
+        raw_conflicts = conflict_detector.detect()
+
+        # 5. Health filter
+        skills_list = [{"skill_id": sid, **sdata} for sid, sdata in fetched.items()]
+        hf = HealthFilter(min_score=request.min_health_score)
+        passed, excluded = hf.filter(skills_list)
+
+        # 6. Apply exclude filter
+        if request.exclude_skills:
+            passed = [s for s in passed if s["skill_id"] not in request.exclude_skills]
+            excluded.extend(request.exclude_skills)
+
+        # 7. Topological sort
+        passed_ids = {s["skill_id"] for s in passed}
+        subgraph = graph.subgraph(passed_ids)
+        sorted_ids = subgraph.topological_sort()
+
+        # 8. Apply max_skills constraint
+        sorted_ids = sorted_ids[: request.max_skills]
+
+        # 9. Build response
+        resolved = []
+        for sid in sorted_ids:
+            sdata = fetched.get(sid, {})
+            # Find conflict severity for this skill
+            conflict_sev = None
+            for c in raw_conflicts:
+                if c["skill_a"] == sid or c["skill_b"] == sid:
+                    conflict_sev = ConflictSeverity(c["severity"])
+                    break
+
+            resolved.append(
+                ResolvedSkill(
+                    skill_id=sid,
+                    name=sdata.get("name", ""),
+                    version=sdata.get("version", "1.0.0"),
+                    dimension=sdata.get("dimension", ""),
+                    domain=sdata.get("domain", ""),
+                    weight=sdata.get("weight", 0.0),
+                    health_score=sdata.get("health_score", 1.0),
+                    trust_level=sdata.get("trust_level", 3),
+                    dependencies=sdata.get("dependencies", []),
+                    estimated_tokens=sdata.get("estimated_tokens", 0),
+                    provides=sdata.get("provides", []),
+                    conflict=conflict_sev,
+                )
+            )
+
+        conflicts = [Conflict(**c) for c in raw_conflicts]
+
+        dag_edges = [
+            DagEdge(source=src, target=tgt, weight=w, type=DagEdgeType.DEPENDS_ON)
+            for src, tgt, w in graph.get_edges()
+            if src in passed_ids and tgt in passed_ids
+        ]
+
+        # Build health_scores mapping
+        health_scores = {s.skill_id: s.health_score for s in resolved}
+
+        # Calculate feasibility_score = f(health_scores, conflicts)
+        avg_health = sum(health_scores.values()) / len(health_scores) if health_scores else 0.0
+        conflict_penalty = len(conflicts) * 0.1  # Each conflict reduces feasibility by 0.1
+        feasibility_score = max(0.0, min(1.0, avg_health - conflict_penalty))
+
+        # Determine status
+        if len(resolved) == 0:
+            status = ResolveStatus.UNRESOLVED
+        elif len(resolved) < len(request.skill_ids):
+            status = ResolveStatus.PARTIAL
+        else:
+            status = ResolveStatus.RESOLVED
+
+        return SkillResolveResponse(
+            resolved=resolved,
+            conflicts=conflicts,
+            excluded=excluded,
+            dag_edges=dag_edges,
+            total_skills=len(resolved),
+            status=status,
+            health_scores=health_scores,
+            feasibility_score=feasibility_score,
+        )
+
+    def _fetch_skills(self, skill_ids: list[str]) -> dict[str, dict]:
+        """Fetch skills from registry, including transitive dependencies.
+
+        When a Registry is configured, reads skill metadata from the Registry
+        (the authoritative source) and skips skills that are not enabled.
+        Otherwise falls back to the in-memory dict store.
+        """
+        fetched: dict[str, dict] = {}
+        queue = list(skill_ids)
+
+        while queue:
+            sid = queue.pop(0)
+            if sid in fetched:
+                continue
+
+            # Try Registry first (authoritative source)
+            if self._registry is not None:
+                record = self._registry.get_skill(sid)
+                if record is None:
+                    continue
+                # Skip non-enabled skills from Registry
+                if not self._registry.is_enabled(sid):
+                    continue
+                meta = record.metadata
+                sdata = {
+                    "name": meta.name,
+                    "version": meta.version,
+                    "dimension": "",
+                    "namespaces": meta.tags,
+                    "dependencies": meta.dependencies,
+                    "weight": meta.quality_score,
+                    "health_score": 1.0,  # Enabled = healthy
+                    "trust_level": 3,
+                }
+            else:
+                sdata = self._registry_store.get(sid)
+                if sdata is None:
+                    continue
+
+            fetched[sid] = sdata
+            # Follow dependencies
+            for dep in sdata.get("dependencies", []):
+                if dep not in fetched:
+                    queue.append(dep)
+
+        return fetched
+
+    def _build_dag(self, skills: dict[str, dict]) -> SkillGraph:
+        """Build a SkillGraph from skill definitions."""
+        graph = SkillGraph()
+        for sid, sdata in skills.items():
+            graph.add_node(sid)
+            for dep in sdata.get("dependencies", []):
+                if dep in skills:
+                    graph.add_edge(dep, sid, weight=sdata.get("weight", 1.0))
+        return graph

skillpool/resolver/cache.py

@@ -0,0 +1,103 @@
+"""Resolver cache — LRU with TTL expiration and thread safety.
+
+Each cache entry has a TTL (default 3600s). Entries past TTL are treated
+as misses and lazily evicted on access.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+import time
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class CacheEntry:
+    """A cached value with expiration timestamp."""
+
+    value: Any
+    expires_at: float  # time.monotonic() timestamp
+
+
+class LRUCache:
+    """LRU cache with TTL expiration and thread-safe operations.
+
+    Args:
+        max_size: Maximum number of entries.
+        ttl_seconds: Time-to-live for each entry (default 3600s).
+    """
+
+    def __init__(self, max_size: int = 128, ttl_seconds: float = 3600.0) -> None:
+        self._max_size = max_size
+        self._ttl_seconds = ttl_seconds
+        self._cache: OrderedDict[str, CacheEntry] = OrderedDict()
+        self._hits = 0
+        self._misses = 0
+        self._lock = threading.Lock()
+
+    @staticmethod
+    def make_key(skill_ids: list[str], **kwargs: object) -> str:
+        """Generate a deterministic cache key from skill_ids and kwargs."""
+        payload = json.dumps({"ids": sorted(skill_ids), **kwargs}, sort_keys=True, default=str)
+        return hashlib.sha256(payload.encode()).hexdigest()[:16]
+
+    def get(self, key: str) -> Optional[Any]:
+        """Get a cached value. Returns None on miss or TTL expiry."""
+        with self._lock:
+            entry = self._cache.get(key)
+            if entry is None:
+                self._misses += 1
+                return None
+            # Check TTL
+            if time.monotonic() > entry.expires_at:
+                del self._cache[key]
+                self._misses += 1
+                return None
+            # Move to end (most recently used)
+            self._cache.move_to_end(key)
+            self._hits += 1
+            return entry.value
+
+    def put(self, key: str, value: Any, ttl_seconds: Optional[float] = None) -> None:
+        """Store a value with optional per-entry TTL override."""
+        with self._lock:
+            ttl = ttl_seconds if ttl_seconds is not None else self._ttl_seconds
+            entry = CacheEntry(value=value, expires_at=time.monotonic() + ttl)
+            if key in self._cache:
+                self._cache.move_to_end(key)
+            self._cache[key] = entry
+            # Evict oldest if over capacity
+            while len(self._cache) > self._max_size:
+                self._cache.popitem(last=False)
+
+    def invalidate(self, key: str) -> bool:
+        """Remove a specific key. Returns True if key existed."""
+        with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+                return True
+            return False
+
+    def clear(self) -> None:
+        """Clear all entries."""
+        with self._lock:
+            self._cache.clear()
+            self._hits = 0
+            self._misses = 0
+
+    def stats(self) -> dict[str, int]:
+        """Return cache hit/miss statistics."""
+        with self._lock:
+            return {"hits": self._hits, "misses": self._misses, "size": len(self._cache)}
+
+    def is_expired(self, key: str) -> bool:
+        """Check if a key exists but is expired (without evicting)."""
+        with self._lock:
+            entry = self._cache.get(key)
+            if entry is None:
+                return False
+            return time.monotonic() > entry.expires_at

skillpool/resolver/circuit_breaker.py

@@ -0,0 +1,103 @@
+"""CircuitBreaker — 3-state circuit breaker for resolver resilience."""
+
+from __future__ import annotations
+
+import time
+from enum import StrEnum
+from typing import Optional
+
+
+class CircuitState(StrEnum):
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+class CircuitBreaker:
+    """3-state circuit breaker: CLOSED → OPEN → HALF_OPEN → CLOSED.
+
+    CLOSED: Normal operation, requests pass through.
+    OPEN: Failures exceeded threshold, requests are rejected.
+    HALF_OPEN: Probe mode, limited requests allowed to test recovery.
+
+    Usage:
+        cb = CircuitBreaker(failure_threshold=5, recovery_timeout=30.0)
+        if cb.allow_request():
+            try:
+                result = do_work()
+                cb.record_success()
+            except Exception:
+                cb.record_failure()
+        else:
+            result = fallback()
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        recovery_timeout: float = 30.0,
+        half_open_max_calls: int = 3,
+    ) -> None:
+        self.failure_threshold = failure_threshold
+        self.recovery_timeout = recovery_timeout
+        self.half_open_max_calls = half_open_max_calls
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._success_count = 0
+        self._last_failure_time: Optional[float] = None
+        self._half_open_calls = 0
+
+    @property
+    def state(self) -> CircuitState:
+        """Current circuit state, with automatic transition from OPEN → HALF_OPEN."""
+        if self._state == CircuitState.OPEN and self._last_failure_time is not None:
+            if time.monotonic() - self._last_failure_time >= self.recovery_timeout:
+                self._state = CircuitState.HALF_OPEN
+                self._half_open_calls = 0
+        return self._state
+
+    def allow_request(self) -> bool:
+        """Check if a request should be allowed through."""
+        current = self.state
+        if current == CircuitState.CLOSED:
+            return True
+        if current == CircuitState.HALF_OPEN:
+            if self._half_open_calls < self.half_open_max_calls:
+                self._half_open_calls += 1
+                return True
+            return False
+        return False  # OPEN
+
+    def record_success(self) -> None:
+        """Record a successful request."""
+        if self._state == CircuitState.HALF_OPEN:
+            self._success_count += 1
+            if self._success_count >= self.half_open_max_calls:
+                self._reset()
+        self._failure_count = 0
+
+    def record_failure(self) -> None:
+        """Record a failed request."""
+        self._failure_count += 1
+        self._last_failure_time = time.monotonic()
+        self._success_count = 0
+
+        if self._state == CircuitState.HALF_OPEN:
+            self._state = CircuitState.OPEN
+        elif self._failure_count >= self.failure_threshold:
+            self._state = CircuitState.OPEN
+
+    def _reset(self) -> None:
+        """Reset to CLOSED state."""
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._success_count = 0
+        self._half_open_calls = 0
+
+    @property
+    def failure_count(self) -> int:
+        return self._failure_count
+
+    @property
+    def success_count(self) -> int:
+        return self._success_count

skillpool/resolver/conflict_detector.py

@@ -0,0 +1,111 @@
+"""ConflictDetector — Jaccard similarity conflict detection between skills."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+
+def _tokenize(text: str) -> set[str]:
+    """Tokenize text into lowercase word set."""
+    return set(re.findall(r"[a-z0-9_]+", text.lower()))
+
+
+def jaccard_similarity(set_a: set[str], set_b: set[str]) -> float:
+    """Compute Jaccard similarity between two sets."""
+    if not set_a and not set_b:
+        return 1.0
+    if not set_a or not set_b:
+        return 0.0
+    intersection = set_a & set_b
+    union = set_a | set_b
+    return len(intersection) / len(union)
+
+
+class ConflictDetector:
+    """Detect naming conflicts between skills using Jaccard similarity.
+
+    Usage:
+        cd = ConflictDetector()
+        cd.register("S01", "Requirement Coverage", "D1", namespaces=["req", "coverage"])
+        conflicts = cd.detect(threshold=0.5)
+    """
+
+    def __init__(self, threshold: float = 0.5) -> None:
+        self.threshold = threshold
+        self._skills: dict[str, dict] = {}  # skill_id → {name, tokens, namespaces}
+
+    def register(
+        self,
+        skill_id: str,
+        name: str = "",
+        dimension: str = "",
+        namespaces: Optional[list[str]] = None,
+    ) -> None:
+        """Register a skill for conflict detection."""
+        tokens = _tokenize(f"{name} {dimension} {' '.join(namespaces or [])}")
+        self._skills[skill_id] = {
+            "name": name,
+            "tokens": tokens,
+            "namespaces": set(namespaces or []),
+        }
+
+    def detect(self, threshold: Optional[float] = None) -> list[dict]:
+        """Detect all pairwise conflicts above threshold.
+
+        Returns list of dicts: {skill_a, skill_b, jaccard_score, severity, overlapping_namespaces}
+        """
+        thresh = threshold if threshold is not None else self.threshold
+        conflicts = []
+        skill_ids = list(self._skills.keys())
+
+        for i in range(len(skill_ids)):
+            for j in range(i + 1, len(skill_ids)):
+                a_id, b_id = skill_ids[i], skill_ids[j]
+                a_info, b_info = self._skills[a_id], self._skills[b_id]
+
+                score = jaccard_similarity(a_info["tokens"], b_info["tokens"])
+                if score >= thresh:
+                    overlapping = a_info["namespaces"] & b_info["namespaces"]
+                    severity = self._classify_severity(score, overlapping)
+                    conflicts.append(
+                        {
+                            "skill_a": a_id,
+                            "skill_b": b_id,
+                            "jaccard_score": round(score, 4),
+                            "severity": severity,
+                            "conflict_type": self._classify_conflict_type(overlapping, score),
+                            "overlapping_namespaces": sorted(overlapping),
+                            "recommendation": self._generate_recommendation(severity, overlapping),
+                        }
+                    )
+
+        return conflicts
+
+    def _classify_severity(self, score: float, overlapping: set[str]) -> str:
+        """Classify conflict severity based on Jaccard score and namespace overlap."""
+        if overlapping and score >= 0.7:
+            return "high"
+        if overlapping or score >= 0.7:
+            return "medium"
+        return "low"
+
+    def _classify_conflict_type(self, overlapping: set[str], score: float) -> str:
+        """Classify conflict type per schema enum."""
+        if overlapping:
+            return "namespace_overlap"
+        if score >= 0.8:
+            return "semantic_conflict"
+        return "namespace_overlap"  # Default for Jaccard-based detection
+
+    def _generate_recommendation(self, severity: str, overlapping: set[str]) -> str:
+        """Generate a recommendation for resolving the conflict."""
+        if severity == "high":
+            return "Consider merging or removing one of the conflicting skills"
+        if severity == "medium":
+            return "Review skill boundaries and adjust namespaces"
+        return "Monitor for potential future conflicts"
+
+    def clear(self) -> None:
+        """Remove all registered skills."""
+        self._skills.clear()

skillpool/resolver/health_filter.py

@@ -0,0 +1,38 @@
+"""HealthFilter — filter skills by health score threshold."""
+
+from __future__ import annotations
+
+
+class HealthFilter:
+    """Filter skills based on health_score.
+
+    Skills with health_score < min_score are excluded.
+
+    Usage:
+        hf = HealthFilter(min_score=0.6)
+        passed, excluded = hf.filter(skills)
+    """
+
+    def __init__(self, min_score: float = 0.6) -> None:
+        self.min_score = min_score
+
+    def filter(self, skills: list[dict]) -> tuple[list[dict], list[str]]:
+        """Filter skills by health_score.
+
+        Args:
+            skills: List of dicts with at least 'skill_id' and 'health_score' keys.
+
+        Returns:
+            Tuple of (passed_skills, excluded_skill_ids)
+        """
+        passed = []
+        excluded = []
+
+        for skill in skills:
+            health = skill.get("health_score", 1.0)
+            if health >= self.min_score:
+                passed.append(skill)
+            else:
+                excluded.append(skill.get("skill_id", "unknown"))
+
+        return passed, excluded