skillpool 4.3.0__py3-none-any.whl

skillpool/synergy/__init__.py

@@ -0,0 +1,240 @@
+"""SynergyDetector — Skill combination gain detection and synergy edge management.
+
+Discovers and manages skill combination synergies:
+1. Loads expert-annotated synergies from CSDF definitions
+2. Creates/updates DagEdge(type=enhances) edges in the skill graph
+3. Discovers new combinations from historical execution data (future: Thompson Sampling)
+
+Part of SkillPool — independent infrastructure, shared by all agents.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from skillpool.config import get_data_dir
+from skillpool.materializer.models import SynergyEntry
+from skillpool.resolver.models import DagEdge, DagEdgeType
+
+logger = logging.getLogger(__name__)
+
+
+class SynergyEdge(BaseModel):
+    """A synergy relationship between two skills with gain data."""
+
+    source: str = Field(description="Primary skill ID")
+    target: str = Field(description="Enhancing skill ID")
+    gain: str = Field(default="", description="Expected gain (e.g. '+15%')")
+    reason: str = Field(default="", description="Why this combination helps")
+    weight: float = Field(default=0.5, ge=0.0, le=1.0, description="Edge weight")
+    evidence: str = Field(default="expert", description="Evidence source: expert/observed/sampled")
+
+
+class SynergyDetectionResult(BaseModel):
+    """Result of synergy detection run."""
+
+    edges_created: int = 0
+    edges_updated: int = 0
+    edges_total: int = 0
+    new_discoveries: list[SynergyEdge] = Field(default_factory=list)
+
+
+class SynergyDetector:
+    """Detects and manages skill combination synergies.
+
+    Usage:
+        detector = SynergyDetector(skills_dir=Path("~/.skillpool/skills"))
+        result = detector.sync_expert_synergies()
+        print(f"Created {result.edges_created} synergy edges")
+    """
+
+    def __init__(self, skills_dir: Path | None = None):
+        self.skills_dir = skills_dir or get_data_dir() / "skills"
+        self._synergy_edges: list[SynergyEdge] = []
+
+    def load_expert_synergies(self) -> list[SynergyEdge]:
+        """Load expert-annotated synergies from CSDF YAML files.
+
+        Reads the `synergies` field from each skill's CSDF definition
+        and converts them to SynergyEdge objects.
+
+        Data source priority: Registry (if available) → local filesystem.
+        All Agents sharing the same MCP server get consistent data.
+        """
+        edges: list[SynergyEdge] = []
+
+        # Primary: try Registry (shared state, consistent across Agents)
+        registry_edges = self._load_from_registry()
+        if registry_edges is not None:
+            self._synergy_edges = registry_edges
+            return registry_edges
+
+        # Fallback: local filesystem (same data, different access path)
+        if not self.skills_dir.exists():
+            return edges
+
+        for skill_dir in self.skills_dir.iterdir():
+            if not skill_dir.is_dir():
+                continue
+
+            # Look for CSDF YAML files
+            for yaml_file in skill_dir.glob("*.yaml"):
+                try:
+                    import yaml
+
+                    data = yaml.safe_load(yaml_file.read_text())
+                    if not data or not isinstance(data, dict):
+                        continue
+
+                    skill_id = data.get("id", skill_dir.name)
+                    synergies = data.get("synergies", [])
+
+                    for syn in synergies:
+                        if isinstance(syn, dict) and "skill_id" in syn:
+                            entry = SynergyEntry(**syn)
+                            # Parse gain percentage to weight
+                            weight = self._parse_gain_to_weight(entry.gain)
+                            edge = SynergyEdge(
+                                source=skill_id,
+                                target=entry.skill_id,
+                                gain=entry.gain,
+                                reason=entry.reason,
+                                weight=weight,
+                                evidence="expert",
+                            )
+                            edges.append(edge)
+                except Exception as e:
+                    logger.warning("Failed to load synergy entry for %s: %s", skill_dir.name, e)
+                    continue
+
+        self._synergy_edges = edges
+        return edges
+
+    def to_dag_edges(self) -> list[DagEdge]:
+        """Convert synergy edges to DagEdge(type=enhances) for the skill graph."""
+        return [
+            DagEdge(
+                source=e.source,
+                target=e.target,
+                weight=e.weight,
+                type=DagEdgeType.ENHANCES,
+            )
+            for e in self._synergy_edges
+        ]
+
+    def sync_expert_synergies(self) -> SynergyDetectionResult:
+        """Full sync: load expert synergies and return detection result.
+
+        This is the main entry point for cold-start synergy setup.
+        """
+        edges = self.load_expert_synergies()
+        _dag_edges = self.to_dag_edges()
+
+        return SynergyDetectionResult(
+            edges_created=len(edges),
+            edges_updated=0,
+            edges_total=len(edges),
+            new_discoveries=[],
+        )
+
+    def get_synergies_for(self, skill_id: str) -> list[SynergyEdge]:
+        """Get all synergy edges where the given skill is the source."""
+        return [e for e in self._synergy_edges if e.source == skill_id]
+
+    def get_enhancers_of(self, skill_id: str) -> list[SynergyEdge]:
+        """Get all skills that enhance the given skill (where target == skill_id)."""
+        return [e for e in self._synergy_edges if e.target == skill_id]
+
+    def load_combination_synergies(self) -> list[SynergyEdge]:
+        """Load synergy edges from PROMOTED and VALIDATING combinations.
+
+        Only includes PROMOTED (full weight) and VALIDATING (reduced weight).
+        DEPRECATED combinations get 0.5x weight. RETIRED are excluded.
+        """
+        try:
+            from skillpool.combiner import CombinationLifecycleManager
+            from skillpool.combiner.models import CombinationLifecycleState
+
+            mgr = CombinationLifecycleManager()
+            all_combos = list(mgr._combinations.values())
+
+            combo_edges: list[SynergyEdge] = []
+            for combo in all_combos:
+                # Skip RETIRED combinations entirely
+                if combo.state == CombinationLifecycleState.RETIRED:
+                    continue
+
+                weight = combo.current_weight()
+
+                # Adjust weight by lifecycle state
+                if combo.state == CombinationLifecycleState.PROMOTED:
+                    pass  # Full weight
+                elif combo.state == CombinationLifecycleState.VALIDATING:
+                    weight *= 0.7  # Reduced confidence
+                elif combo.state == CombinationLifecycleState.DEPRECATED:
+                    weight *= 0.5  # Significantly reduced
+                elif combo.state == CombinationLifecycleState.DISCOVERED:
+                    weight *= 0.3  # Low weight, untested
+                elif combo.state == CombinationLifecycleState.REJECTED:
+                    continue  # Skip rejected
+
+                if weight < 0.05:
+                    continue
+
+                for enhancer in combo.enhancers:
+                    edge = SynergyEdge(
+                        source=combo.primary,
+                        target=enhancer,
+                        gain=f"+{combo.gain_avg:.1f}%",
+                        reason=f"{CombinationLifecycleState(combo.state).name} combination "
+                        f"(source={combo.source}, executions={combo.execution_count})",
+                        weight=round(weight, 3),
+                        evidence="observed" if combo.state == CombinationLifecycleState.PROMOTED else "exploratory",
+                    )
+                    combo_edges.append(edge)
+
+            # Merge with existing synergy edges (dedup by source+target)
+            existing = {(e.source, e.target) for e in self._synergy_edges}
+            new_edges = [e for e in combo_edges if (e.source, e.target) not in existing]
+            self._synergy_edges.extend(new_edges)
+            return new_edges
+
+        except (ImportError, Exception):
+            return []
+
+    @staticmethod
+    def _parse_gain_to_weight(gain: str) -> float:
+        """Parse gain string like '+15%' to a weight between 0 and 1.
+
+        Maps: +5% → 0.3, +10% → 0.5, +15% → 0.65, +20% → 0.8, +25%+ → 0.9
+        """
+        try:
+            pct = float(gain.strip().replace("+", "").replace("%", ""))
+            # Sigmoid-like mapping: higher gains → higher weights
+            # Clamped to [0.1, 0.95]
+            weight = min(0.95, max(0.1, pct / 30.0))
+            return round(weight, 2)
+        except (ValueError, AttributeError):
+            return 0.5  # Default weight when gain is not parseable
+
+    def _load_from_registry(self) -> list[SynergyEdge] | None:
+        """Try loading synergies from the Registry (shared state).
+
+        Returns None if Registry not available or has no synergy data,
+        triggering filesystem fallback. Returns list if data found.
+        """
+        try:
+            from skillpool.registry import Registry
+
+            _registry = Registry()
+            # Registry stores skills with metadata; check for synergy annotations
+            # Currently, Registry doesn't store CSDF synergies directly,
+            # so this returns None to trigger filesystem read.
+            # Future: when Registry supports synergy metadata, this will
+            # be the primary path for remote Agents.
+            return None
+        except (ImportError, Exception):
+            return None

skillpool/synergy/detector.py

@@ -0,0 +1,5 @@
+"""SynergyDetector — Skill combination gain detection."""
+
+from skillpool.synergy import SynergyDetector, SynergyEdge, SynergyDetectionResult
+
+__all__ = ["SynergyDetector", "SynergyEdge", "SynergyDetectionResult"]

skillpool/telemetry.py

@@ -0,0 +1,126 @@
+"""
+TelemetryBridge — 反向反馈通道，将运行时信号传回 SkillPool。
+
+3 个通道:
+  1. hook  — Claude Code / Codex hook 事件（PreToolUse, PostToolUse, Stop 等）
+  2. mcp   — MCP tool call（由 mcp_server.py 暴露 telemetry_report 工具）
+  3. log_file — 文件轮询（兼容无 hook/MCP 的环境）
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from enum import StrEnum
+from pathlib import Path
+from typing import Optional, Callable
+
+from skillpool.config import get_data_dir
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class TelemetryChannel(StrEnum):
+    HOOK = "hook"
+    MCP = "mcp"
+    LOG_FILE = "log_file"
+
+
+class TelemetryEvent(BaseModel):
+    """单条遥测事件。"""
+
+    event_type: str
+    skill_id: str
+    channel: TelemetryChannel = TelemetryChannel.LOG_FILE
+    payload: dict = {}
+    timestamp: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    trace_id: str = ""
+
+
+class TelemetryBridge:
+    """反向反馈通道 — 从运行时向 SkillPool 传递遥测信号。
+
+    Usage:
+        bridge = TelemetryBridge(log_dir=Path("~/.skillpool/telemetry"))
+        bridge.emit("skill_used", skill_id="S05a", channel="hook")
+        bridge.emit("skill_error", skill_id="S10", channel="mcp", payload={"error": "timeout"})
+    """
+
+    def __init__(self, log_dir: Optional[Path] = None):
+        self.log_dir = log_dir or get_data_dir() / "telemetry"
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        self._hooks: list[Callable] = []
+
+    def emit(
+        self,
+        event_type: str,
+        skill_id: str,
+        channel: TelemetryChannel | str = TelemetryChannel.LOG_FILE,
+        payload: Optional[dict] = None,
+        trace_id: str = "",
+    ) -> TelemetryEvent:
+        """发射一条遥测事件。同时写入 log_file 并调用已注册的 hook。"""
+        ch = TelemetryChannel(channel) if isinstance(channel, str) else channel
+        event = TelemetryEvent(
+            event_type=event_type,
+            skill_id=skill_id,
+            channel=ch,
+            payload=payload or {},
+            trace_id=trace_id,
+        )
+
+        # 始终写入 log_file
+        self._write_to_log(event)
+
+        # 调用注册的 hook
+        for hook_fn in self._hooks:
+            try:
+                hook_fn(event)
+            except Exception as e:
+                logger.warning("Telemetry hook callback failed: %s", e)
+
+        return event
+
+    def register_hook(self, fn: Callable) -> None:
+        """注册一个 hook 回调，每次 emit 时调用。"""
+        self._hooks.append(fn)
+
+    def read_events(
+        self,
+        skill_id: Optional[str] = None,
+        event_type: Optional[str] = None,
+        since: Optional[float] = None,
+    ) -> list[TelemetryEvent]:
+        """从 log_file 读取历史事件。"""
+        events = []
+        log_file = self.log_dir / f"telemetry-{datetime.now().strftime('%Y%m%d')}.jsonl"
+        if not log_file.exists():
+            return events
+
+        for line in log_file.read_text().strip().split("\n"):
+            if not line:
+                continue
+            try:
+                data = json.loads(line)
+                event = TelemetryEvent(**data)
+                if skill_id and event.skill_id != skill_id:
+                    continue
+                if event_type and event.event_type != event_type:
+                    continue
+                if since:
+                    evt_ts = datetime.fromisoformat(event.timestamp).timestamp()
+                    if evt_ts < since:
+                        continue
+                events.append(event)
+            except (json.JSONDecodeError, Exception):
+                continue
+
+        return events
+
+    def _write_to_log(self, event: TelemetryEvent) -> None:
+        """追加写入当日 JSONL 文件。"""
+        log_file = self.log_dir / f"telemetry-{datetime.now().strftime('%Y%m%d')}.jsonl"
+        with open(log_file, "a") as f:
+            f.write(event.model_dump_json() + "\n")

skillpool/utils/__init__.py

@@ -0,0 +1,21 @@
+"""SkillPool utility modules."""
+
+from __future__ import annotations
+
+__all__ = [
+    "ConsoleRenderer",
+    "ContextVarsBinding",
+    "JSONRenderer",
+    "RuntimeAuditHook",
+    "SkillPoolLogger",
+    "utc_now",
+]
+
+from skillpool.utils.time_utils import utc_now
+from skillpool.utils.runtime_audit import RuntimeAuditHook
+from skillpool.utils.logger import (
+    ConsoleRenderer,
+    ContextVarsBinding,
+    JSONRenderer,
+    SkillPoolLogger,
+)

skillpool/utils/changelog.py

@@ -0,0 +1,218 @@
+"""Changelog utilities — auto-append entries to CHANGELOG.md.
+
+Reads the project CHANGELOG.md, finds the current version section,
+and appends structured entries under the appropriate category subsection.
+
+Categories: Added, Fixed, Changed, Deprecated, Removed, Security
+"""
+
+from __future__ import annotations
+
+__all__ = ["append_changelog_entry"]
+
+import re
+from datetime import date
+from pathlib import Path
+
+# Default changelog path
+_CHANGELOG_PATH = Path(__file__).resolve().parent.parent.parent.parent / "CHANGELOG.md"
+
+# Valid categories (Keep a Changelog standard)
+VALID_CATEGORIES = frozenset(
+    {
+        "Added",
+        "Fixed",
+        "Changed",
+        "Deprecated",
+        "Removed",
+        "Security",
+    }
+)
+
+
+def _detect_current_version(content: str) -> str | None:
+    """Detect the current (most recent) version from CHANGELOG content.
+
+    Looks for the first '## [X.Y.Z]' header.
+
+    Args:
+        content: Full CHANGELOG.md content.
+
+    Returns:
+        Version string (e.g., '4.2.0') or None if not found.
+    """
+    match = re.search(r"^## \[(\d+\.\d+\.\d+)\]", content, re.MULTILINE)
+    return match.group(1) if match else None
+
+
+def _find_version_section_end(content: str, version: str) -> int | None:
+    """Find the line index where the next version section starts.
+
+    Args:
+        content: Full CHANGELOG.md content split into lines.
+        version: Version string to find.
+
+    Returns:
+        Line index of the next version header, or len(lines) if last section.
+    """
+    lines = content.split("\n")
+    found_current = False
+    for i, line in enumerate(lines):
+        if re.match(rf"^## \[{re.escape(version)}\]", line):
+            found_current = True
+            continue
+        if found_current and re.match(r"^## \[", line):
+            return i
+    return len(lines) if found_current else None
+
+
+def _find_or_create_category(
+    lines: list[str],
+    section_start: int,
+    section_end: int,
+    category: str,
+) -> int:
+    """Find the line index where a category subsection starts, or determine
+    where to insert it.
+
+    Args:
+        lines: CHANGELOG.md split into lines.
+        section_start: Line index of the version header.
+        section_end: Line index of the next version header (or len(lines)).
+        category: Category name (e.g., 'Fixed').
+
+    Returns:
+        Line index where entries for this category should be appended.
+        If the category subsection exists, returns the line after its last entry.
+        If not, returns the line where the subsection header should be inserted.
+    """
+    category_header = f"### {category}"
+
+    # Search for existing category subsection within the version section
+    category_start = None
+    next_category_start = None
+
+    for i in range(section_start, section_end):
+        if lines[i].strip() == category_header:
+            category_start = i
+            break
+
+    if category_start is not None:
+        # Found the category — find where it ends (next ### or ## or end of section)
+        for i in range(category_start + 1, section_end):
+            if re.match(r"^### ", lines[i]) or re.match(r"^## ", lines[i]):
+                next_category_start = i
+                break
+
+        if next_category_start is not None:
+            # Find the last non-empty line before the next subsection
+            insert_at = next_category_start
+            for i in range(next_category_start - 1, category_start, -1):
+                if lines[i].strip():
+                    insert_at = i + 1
+                    break
+            return insert_at
+        else:
+            # Category is the last subsection — append at end of section
+            insert_at = section_end
+            for i in range(section_end - 1, category_start, -1):
+                if lines[i].strip():
+                    insert_at = i + 1
+                    break
+            return insert_at
+    else:
+        # Category doesn't exist — insert after the version header
+        # Find the first ### or non-empty line after the version header
+        insert_at = section_start + 1
+        for i in range(section_start + 1, section_end):
+            stripped = lines[i].strip()
+            if stripped.startswith("### ") or stripped.startswith("#### "):
+                insert_at = i
+                break
+            if stripped and not stripped.startswith("---"):
+                insert_at = i
+                break
+
+        return insert_at
+
+
+def append_changelog_entry(
+    category: str,
+    description: str,
+    details: dict | None = None,
+    changelog_path: Path | str | None = None,
+) -> None:
+    """Append a structured entry to CHANGELOG.md under current version section.
+
+    Categories: Added, Fixed, Changed, Deprecated, Removed, Security
+
+    Writes a single line entry with timestamp and auto-detection of current version.
+
+    Args:
+        category: Changelog category (Added, Fixed, Changed, etc.).
+        description: Short description of the change.
+        details: Optional dict with additional context. If provided, rendered
+                 as key=value pairs in the entry.
+        changelog_path: Override for CHANGELOG.md path (default: project root).
+
+    Raises:
+        ValueError: If category is not a valid Keep a Changelog category.
+        FileNotFoundError: If CHANGELOG.md does not exist.
+    """
+    if category not in VALID_CATEGORIES:
+        raise ValueError(f"Invalid category '{category}'. Must be one of: {', '.join(sorted(VALID_CATEGORIES))}")
+
+    path = Path(changelog_path) if changelog_path else _CHANGELOG_PATH
+
+    if not path.exists():
+        raise FileNotFoundError(f"CHANGELOG.md not found at {path}")
+
+    content = path.read_text(encoding="utf-8")
+    version = _detect_current_version(content)
+
+    if version is None:
+        raise ValueError("No version section found in CHANGELOG.md")
+
+    lines = content.split("\n")
+
+    # Find the version section boundaries
+    section_start = None
+    for i, line in enumerate(lines):
+        if re.match(rf"^## \[{re.escape(version)}\]", line):
+            section_start = i
+            break
+
+    if section_start is None:
+        raise ValueError(f"Version section [{version}] not found in CHANGELOG.md")
+
+    section_end = _find_version_section_end(content, version)
+    if section_end is None:
+        section_end = len(lines)
+
+    # Find where to insert the entry
+    insert_at = _find_or_create_category(lines, section_start, section_end, category)
+
+    # Build the entry line
+    today = date.today().isoformat()
+    details_str = ""
+    if details:
+        details_str = " ".join(f"{k}={v}" for k, v in details.items())
+        details_str = f" ({details_str})"
+
+    entry_line = f"- **{description}**:{details_str} ({today})"
+
+    # Check if the category subsection header needs to be created
+    category_header = f"### {category}"
+    category_exists = any(lines[i].strip() == category_header for i in range(section_start, section_end))
+
+    if category_exists:
+        # Just insert the entry line
+        lines.insert(insert_at, entry_line)
+    else:
+        # Insert category header + blank line + entry
+        lines.insert(insert_at, entry_line)
+        lines.insert(insert_at, "")
+        lines.insert(insert_at, category_header)
+
+    # Write back
+    path.write_text("\n".join(lines), encoding="utf-8")