caudate-cli 0.1.0__py3-none-any.whl

core/skills.py

@@ -0,0 +1,398 @@
+"""Skills — markdown-defined capability packs for Cognos.
+
+Compatible with the open `vercel-labs/skills` ecosystem: a "skill" is
+a directory containing a `SKILL.md` file with YAML frontmatter
+(`name`, `description`) and markdown instructions.
+
+Cognos scans three locations:
+  - `~/.cognos/skills/`          — Cognos-specific
+  - `~/.claude/skills/`          — Claude Code's standard location (compat)
+  - `<repo>/skills/`             — bundled with this checkout
+
+At chat time, the names + descriptions are injected into the system
+prompt as a *table of contents*. The LLM calls `LoadSkill(name)` to
+pull the full body of a skill it deems relevant. This keeps the
+default prompt size bounded even with dozens of skills installed.
+
+Skills are pure markdown — no runtime, no code execution. They're
+prompt-engineering instructions the LLM follows.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+# Default scan locations. Order matters: later entries override earlier
+# ones if names collide (later wins → repo skills override globals).
+DEFAULT_SKILL_DIRS: tuple[Path, ...] = (
+    Path.home() / ".claude" / "skills",
+    Path.home() / ".cognos" / "skills",
+    Path("/home/raveuk/cognos/skills"),
+)
+
+
+@dataclass
+class Skill:
+    """One markdown-defined capability pack."""
+    name: str
+    description: str
+    body: str            # the markdown instructions (no frontmatter)
+    path: Path           # source SKILL.md
+    source_dir: Path     # which scan dir it came from
+
+    @property
+    def header(self) -> str:
+        """One-line summary used in the system-prompt table of contents."""
+        desc = self.description or "(no description)"
+        return f"- **{self.name}** — {desc[:160]}"
+
+
+# ---------------------------------------------------------------------
+# Parsing
+# ---------------------------------------------------------------------
+
+
+def _parse_frontmatter(text: str) -> tuple[dict[str, str], str]:
+    """Split YAML-frontmatter markdown into (metadata, body).
+
+    We do a minimal hand-roll instead of pulling in PyYAML — skills
+    only use scalar string fields (name, description), not nested
+    structures. This avoids adding a runtime dependency.
+    """
+    if not text.startswith("---"):
+        return {}, text
+    end_marker = text.find("\n---", 3)
+    if end_marker < 0:
+        return {}, text
+    fm_block = text[3:end_marker].strip()
+    body_start = end_marker + 4
+    if body_start < len(text) and text[body_start] == "\n":
+        body_start += 1
+    body = text[body_start:].strip()
+
+    meta: dict[str, str] = {}
+    for line in fm_block.splitlines():
+        line = line.rstrip()
+        if not line or line.startswith("#"):
+            continue
+        # Naive key:value, supports quoted scalars + multi-word values
+        if ":" in line:
+            k, _, v = line.partition(":")
+            v = v.strip()
+            # Strip surrounding quotes
+            if (len(v) >= 2 and v[0] == v[-1]
+                    and v[0] in ('"', "'")):
+                v = v[1:-1]
+            meta[k.strip()] = v
+    return meta, body
+
+
+def _load_skill(skill_md: Path, source_dir: Path) -> Skill | None:
+    try:
+        text = skill_md.read_text()
+    except OSError as e:
+        logger.warning(f"Failed to read {skill_md}: {e}")
+        return None
+    meta, body = _parse_frontmatter(text)
+    name = (meta.get("name") or skill_md.parent.name).strip()
+    description = (meta.get("description") or "").strip()
+    if not name:
+        return None
+    return Skill(
+        name=name,
+        description=description,
+        body=body,
+        path=skill_md,
+        source_dir=source_dir,
+    )
+
+
+# ---------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------
+
+
+@dataclass
+class SkillRegistry:
+    """In-memory index of all loaded skills, keyed by name."""
+
+    skills: dict[str, Skill] = field(default_factory=dict)
+    scanned_dirs: list[Path] = field(default_factory=list)
+
+    def reload(self, dirs: tuple[Path, ...] = DEFAULT_SKILL_DIRS) -> None:
+        """Rescan all configured directories. Idempotent."""
+        self.skills.clear()
+        self.scanned_dirs = []
+        for root in dirs:
+            self.scanned_dirs.append(root)
+            if not root.exists():
+                continue
+            for skill_md in root.rglob("SKILL.md"):
+                skill = _load_skill(skill_md, root)
+                if skill is None:
+                    continue
+                # Last-wins for duplicate names
+                self.skills[skill.name] = skill
+
+    def list_names(self) -> list[str]:
+        return sorted(self.skills.keys())
+
+    def get(self, name: str) -> Skill | None:
+        return self.skills.get(name)
+
+    def render_toc(self) -> str:
+        """Format the skills as a system-prompt table of contents.
+
+        Returns empty string if no skills are loaded — avoids polluting
+        the prompt with "no skills installed" boilerplate.
+        """
+        if not self.skills:
+            return ""
+        lines = [
+            "## Available skills",
+            "",
+            "Skills are markdown capability packs. Use `LoadSkill(name=...)` "
+            "to read the full instructions for any of these when relevant:",
+            "",
+        ]
+        for skill in sorted(self.skills.values(), key=lambda s: s.name.lower()):
+            lines.append(skill.header)
+        return "\n".join(lines)
+
+    def find_relevant(
+        self,
+        user_text: str,
+        top_k: int = 2,
+        min_score: float = 0.18,
+    ) -> list[tuple["Skill", float]]:
+        """Score skills against a free-form user prompt; return the top-K.
+
+        Scoring strategy: split everything (name, description, prompt)
+        into alnum-only tokens (so 'deploy-to-vercel' → {'deploy',
+        'to', 'vercel'} after stop-word filtering), then score on
+        TWO axes:
+
+          1. user_coverage — what fraction of the user's distinctive
+             tokens does this skill cover? Catches "user mentioned
+             vercel and deploy → vercel skill is relevant".
+          2. name_match    — what fraction of the skill's NAME tokens
+             showed up in the user prompt? Strong signal because the
+             name is a curated label.
+
+        Final score = user_coverage * 0.5 + name_match * 0.5.
+        Default threshold 0.18 catches strong matches without firing
+        on every passing keyword.
+        """
+        if not user_text or not self.skills:
+            return []
+
+        def _tokens(s: str) -> set[str]:
+            # Split on any non-alnum character — gives us the components
+            # of hyphen-words like 'deploy-to-vercel' separately.
+            import re
+            tokens = re.findall(r"[a-z0-9]+", s.lower())
+            return {t for t in tokens if len(t) > 2 and t not in _STOP}
+
+        user_tokens = _tokens(user_text)
+        if not user_tokens:
+            return []
+
+        scored: list[tuple[Skill, float]] = []
+        for skill in self.skills.values():
+            name_tokens = _tokens(skill.name)
+            desc_tokens = _tokens(skill.description)
+            all_skill_tokens = name_tokens | desc_tokens
+            if not all_skill_tokens:
+                continue
+            overlap = user_tokens & all_skill_tokens
+            if not overlap:
+                continue
+            user_coverage = len(overlap) / len(user_tokens)
+            name_match = (len(user_tokens & name_tokens)
+                          / max(1, len(name_tokens)))
+            score = user_coverage * 0.5 + name_match * 0.5
+            if score >= min_score:
+                scored.append((skill, score))
+        scored.sort(key=lambda p: p[1], reverse=True)
+        return scored[:top_k]
+
+    def render_active_skills(self, user_text: str, top_k: int = 2) -> str:
+        """Auto-activate the top-K skills relevant to a user prompt and
+        return their FULL bodies for system-prompt injection.
+
+        Returns empty string if nothing matches. The chat path injects
+        this output below the TOC so the LLM both knows about all
+        skills (TOC) AND has the full instructions for the most-likely-
+        relevant ones already in-context (no LoadSkill round-trip).
+        """
+        matches = self.find_relevant(user_text, top_k=top_k)
+        if not matches:
+            return ""
+        parts = [
+            "## Active skills (auto-selected for this turn)",
+            "",
+            "These skills look relevant to the user's prompt. **Follow "
+            "their instructions when they apply** — they are more "
+            "specific and current than your training defaults. Other "
+            "skills are listed in the TOC above; LoadSkill if needed.",
+        ]
+        for skill, score in matches:
+            parts.append(f"\n### {skill.name}  _(relevance ≈ {score:.2f})_")
+            if skill.description:
+                parts.append(f"_{skill.description}_\n")
+            parts.append(skill.body)
+        return "\n".join(parts)
+
+
+# Common stop words, dropped from token sets so they don't drive bogus
+# matches. Not exhaustive — just the worst offenders.
+_STOP: frozenset[str] = frozenset({
+    "the", "and", "for", "with", "from", "that", "this", "have",
+    "was", "were", "will", "are", "you", "your", "want", "would",
+    "could", "should", "what", "when", "where", "how", "why", "who",
+    "can", "all", "any", "but", "not", "they", "them", "their", "his",
+    "her", "she", "him", "its", "our", "out", "use", "using", "into",
+})
+
+
+# ---------------------------------------------------------------------
+# Module-level singleton (lazy)
+# ---------------------------------------------------------------------
+
+
+_registry: SkillRegistry | None = None
+
+
+def get_skills() -> SkillRegistry:
+    global _registry
+    if _registry is None:
+        _registry = SkillRegistry()
+        _registry.reload()
+        logger.info(
+            f"SkillRegistry loaded {len(_registry.skills)} skill(s) "
+            f"from {len(_registry.scanned_dirs)} dirs"
+        )
+    return _registry
+
+
+def reload_skills() -> SkillRegistry:
+    """Force re-scan of all skill directories. Use after `npx skills add ...`."""
+    global _registry
+    if _registry is None:
+        _registry = SkillRegistry()
+    _registry.reload()
+    return _registry
+
+
+# ---------------------------------------------------------------------
+# Lockfile — pin skill content hashes so silent edits are caught
+# ---------------------------------------------------------------------
+#
+# LocalForge calls this its "skills lockfile". It records a SHA-256 of
+# every SKILL.md so a `cognos skills verify` run can flag any skill
+# that drifted between deploys (someone hand-edited the markdown,
+# upstream pushed an update, etc.). Tier 3 in the LocalForge plan but
+# valuable: it makes "what skills did this build of Cognos ship with?"
+# answerable. The lock is written to data/skills.lock.json.
+
+import hashlib
+import json
+from datetime import datetime, timezone
+
+LOCKFILE_PATH = Path(__file__).resolve().parents[1] / "data" / "skills.lock.json"
+
+
+def _hash_skill(skill: Skill) -> str:
+    """Stable SHA-256 of the SKILL.md raw bytes."""
+    try:
+        return hashlib.sha256(skill.path.read_bytes()).hexdigest()
+    except OSError:
+        return ""
+
+
+def lock_skills(reg: SkillRegistry | None = None,
+                lock_path: Path | None = None,
+                dirs: tuple[Path, ...] | None = None) -> dict:
+    """Compute hashes for every loaded skill and write the lockfile.
+
+    Returns the dict that was written.
+    """
+    if reg is None:
+        if dirs is not None:
+            reg = SkillRegistry()
+            reg.reload(dirs=dirs)
+        else:
+            reg = get_skills()
+    if lock_path is None:
+        lock_path = LOCKFILE_PATH
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+
+    entries: list[dict] = []
+    for name in sorted(reg.skills):
+        skill = reg.skills[name]
+        entries.append({
+            "name": skill.name,
+            "description": skill.description,
+            "path": str(skill.path),
+            "source_dir": str(skill.source_dir),
+            "sha256": _hash_skill(skill),
+            "size_bytes": skill.path.stat().st_size if skill.path.exists() else 0,
+        })
+    payload = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "count": len(entries),
+        "skills": entries,
+    }
+    lock_path.write_text(json.dumps(payload, indent=2))
+    return payload
+
+
+def verify_skills(lock_path: Path | None = None,
+                  dirs: tuple[Path, ...] | None = None) -> dict:
+    """Compare the live filesystem to a lockfile.
+
+    Returns a report dict::
+
+        {
+          "ok": bool,
+          "missing": [name, …]   # in lock but no longer on disk
+          "added":   [name, …]   # on disk but not in lock
+          "changed": [name, …]   # hash mismatch
+          "unchanged": int,
+        }
+    """
+    if lock_path is None:
+        lock_path = LOCKFILE_PATH
+    if not lock_path.exists():
+        return {"ok": False, "error": f"lockfile not found: {lock_path}"}
+
+    lock = json.loads(lock_path.read_text())
+    locked = {e["name"]: e for e in lock.get("skills", [])}
+
+    reg = SkillRegistry()
+    reg.reload(dirs=dirs) if dirs is not None else reg.reload()
+    live = {name: _hash_skill(skill) for name, skill in reg.skills.items()}
+
+    missing = [n for n in locked if n not in live]
+    added = [n for n in live if n not in locked]
+    changed = [
+        n for n in locked
+        if n in live and live[n] != locked[n].get("sha256")
+    ]
+    unchanged = sum(
+        1 for n in locked
+        if n in live and live[n] == locked[n].get("sha256")
+    )
+    return {
+        "ok": not (missing or added or changed),
+        "missing": missing,
+        "added": added,
+        "changed": changed,
+        "unchanged": unchanged,
+        "lock_path": str(lock_path),
+    }