skill-router 0.0.1-snapshot

package/README.md

@@ -0,0 +1,48 @@
+# skill-router
+
+Local semantic skill router for `gemini-cli-pro`.
+
+## Install
+
+```bash
+npm install -g .
+```
+
+The package runs this postinstall hook:
+
+```bash
+python3 -m pip install fastembed numpy --user
+```
+
+## Usage
+
+```bash
+skill-router --prompt "rename API layer" --skills-dir /path/to/.skills
+```
+
+Output is always JSON:
+
+```json
+{"skill_id":"node-backend","score":0.8732}
+```
+
+If score is below threshold:
+
+```json
+{"skill_id":null,"score":0.0}
+```
+
+If the provided `--skills-dir` does not exist or has no `.md` files, it returns:
+
+```json
+{"skill_id":null,"score":0.0}
+```
+
+## Cache
+
+Cache is stored in:
+
+- `~/.cache/skill-router/data.npy`
+- `~/.cache/skill-router/.skills_cache.npy`
+
+Works on Ubuntu/Linux and macOS.

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "skill-router",
+  "version": "0.0.1-snapshot",
+  "description": "Local semantic skill router for gemini-cli-pro",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "skill-router": "./router.py"
+  },
+  "scripts": {
+    "postinstall": "python3 -m pip install fastembed numpy --user"
+  },
+  "files": [
+    "router.py",
+    "README.md"
+  ]
+}

package/router.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""skill-router: local semantic router for Gemini CLI skills."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Iterable
+
+import numpy as np
+
+try:
+    from fastembed import TextEmbedding
+except Exception:  # pragma: no cover - runtime dependency may be unavailable
+    TextEmbedding = None
+
+
+MODEL_NAME = "BAAI/bge-small-en-v1.5"
+CACHE_ROOT = Path.home() / ".cache" / "skill-router"
+DATA_FILE = CACHE_ROOT / "data.npy"
+SKILLS_CACHE_FILE = CACHE_ROOT / ".skills_cache.npy"
+
+_EMBEDDER = None
+
+
+class JsonArgumentParser(argparse.ArgumentParser):
+    """Argument parser that always prints JSON on errors."""
+
+    def error(self, message: str) -> None:
+        payload = {
+            "skill_id": None,
+            "score": 0.0,
+            "error": f"invalid_arguments: {message}",
+        }
+        print(json.dumps(payload, ensure_ascii=False))
+        raise SystemExit(2)
+
+
+def _ok(skill_id: str | None, score: float) -> dict:
+    return {
+        "skill_id": skill_id,
+        "score": round(float(score), 4),
+    }
+
+
+def _err(message: str) -> dict:
+    return {
+        "skill_id": None,
+        "score": 0.0,
+        "error": message,
+    }
+
+
+def _ensure_cache_dir() -> None:
+    try:
+        CACHE_ROOT.mkdir(parents=True, exist_ok=True)
+    except PermissionError as exc:
+        raise RuntimeError("cache_write_permission_denied") from exc
+    except OSError as exc:
+        raise RuntimeError(f"cache_init_failed: {exc}") from exc
+
+
+def _iter_skill_files(skills_dir: Path) -> Iterable[Path]:
+    for path in sorted(skills_dir.rglob("*.md")):
+        if path.is_file():
+            yield path
+
+
+def _has_skill_markdown(skills_dir: Path) -> bool:
+    if not skills_dir.exists() or not skills_dir.is_dir():
+        return False
+    return any(True for _ in _iter_skill_files(skills_dir))
+
+
+def _resolve_available_skills_dir(preferred_skills_dir: Path) -> Path | None:
+    candidate = preferred_skills_dir.resolve()
+    if _has_skill_markdown(candidate):
+        return candidate
+    return None
+
+
+def _normalize_heading(text: str) -> str:
+    return (
+        text.strip()
+        .lower()
+        .replace("#", "")
+        .replace(":", "")
+        .replace("\u00a0", " ")
+        .strip()
+    )
+
+
+def _extract_section(content: str, headings: set[str]) -> str:
+    lines = content.splitlines()
+    capture = False
+    bucket: list[str] = []
+
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("###"):
+            current = _normalize_heading(stripped)
+            if current in headings:
+                capture = True
+                continue
+            if capture:
+                break
+        if capture:
+            bucket.append(line)
+
+    return "\n".join(bucket).strip()
+
+
+def _skill_id_for_path(path: Path, skills_dir: Path) -> str:
+    if path.stem.lower() == "skill" and path.parent != skills_dir:
+        return path.parent.name
+    return path.stem
+
+
+def _extract_index_text(content: str) -> str:
+    triggers = _extract_section(content, {"gatilhos", "triggers"})
+    description = _extract_section(content, {"descricao", "descrição", "description"})
+
+    merged = "\n\n".join(part for part in [triggers, description] if part).strip()
+    if merged:
+        return merged
+
+    # Fallback: if sections do not exist, index the first relevant chunk.
+    return content.strip()[:2000]
+
+
+def _compute_skills_hash(skills_dir: Path) -> str:
+    digest = hashlib.sha256()
+
+    for path in _iter_skill_files(skills_dir):
+        rel = path.relative_to(skills_dir).as_posix()
+        digest.update(rel.encode("utf-8"))
+        stat = path.stat()
+        digest.update(str(stat.st_mtime_ns).encode("utf-8"))
+        digest.update(str(stat.st_size).encode("utf-8"))
+        with path.open("rb") as fh:
+            while True:
+                chunk = fh.read(8192)
+                if not chunk:
+                    break
+                digest.update(chunk)
+
+    return digest.hexdigest()
+
+
+def _get_embedder() -> TextEmbedding:
+    global _EMBEDDER
+    if _EMBEDDER is None:
+        if TextEmbedding is None:
+            raise RuntimeError("missing_dependency: fastembed")
+        _EMBEDDER = TextEmbedding(model_name=MODEL_NAME)
+    return _EMBEDDER
+
+
+def index_skills(skills_dir: Path) -> dict:
+    if not skills_dir.exists() or not skills_dir.is_dir():
+        raise RuntimeError(f"skills_dir_not_found: {skills_dir}")
+
+    skill_files = list(_iter_skill_files(skills_dir))
+    if not skill_files:
+        raise RuntimeError("skills_dir_empty")
+
+    _ensure_cache_dir()
+    skills_hash = _compute_skills_hash(skills_dir)
+
+    ids: list[str] = []
+    texts: list[str] = []
+    seen: dict[str, int] = {}
+
+    for path in skill_files:
+        content = path.read_text(encoding="utf-8", errors="ignore")
+        index_text = _extract_index_text(content)
+        if not index_text:
+            continue
+
+        skill_id = _skill_id_for_path(path, skills_dir)
+        if skill_id in seen:
+            seen[skill_id] += 1
+            skill_id = f"{skill_id}-{seen[skill_id]}"
+        else:
+            seen[skill_id] = 1
+
+        ids.append(skill_id)
+        texts.append(index_text)
+
+    if not ids:
+        raise RuntimeError("no_valid_skill_content")
+
+    embedder = _get_embedder()
+    vectors = list(embedder.embed(texts))
+    matrix = np.vstack(vectors).astype(np.float32)
+
+    data_payload = {
+        "skills_hash": skills_hash,
+        "skills_dir": str(skills_dir.resolve()),
+        "ids": ids,
+        "matrix": matrix,
+    }
+
+    # Main cache requested by spec.
+    np.save(DATA_FILE, data_payload, allow_pickle=True)
+
+    # Marker cache requested by spec for hash invalidation checks.
+    marker_payload = {
+        "skills_hash": skills_hash,
+        "skills_dir": str(skills_dir.resolve()),
+    }
+    np.save(SKILLS_CACHE_FILE, marker_payload, allow_pickle=True)
+
+    return {
+        "indexed": len(ids),
+        "skills_hash": skills_hash,
+    }
+
+
+def _load_cache_payload() -> dict:
+    if not DATA_FILE.exists():
+        raise RuntimeError("cache_data_missing")
+    data = np.load(DATA_FILE, allow_pickle=True)
+    payload = data.item() if hasattr(data, "item") else data
+    if not isinstance(payload, dict):
+        raise RuntimeError("cache_data_invalid")
+    return payload
+
+
+def _needs_reindex(skills_dir: Path) -> bool:
+    if not DATA_FILE.exists() or not SKILLS_CACHE_FILE.exists():
+        return True
+
+    try:
+        marker = np.load(SKILLS_CACHE_FILE, allow_pickle=True)
+        meta = marker.item() if hasattr(marker, "item") else marker
+        if not isinstance(meta, dict):
+            return True
+
+        cached_hash = meta.get("skills_hash")
+        cached_dir = meta.get("skills_dir")
+    except Exception:
+        return True
+
+    current_hash = _compute_skills_hash(skills_dir)
+    return (
+        cached_hash != current_hash
+        or cached_dir != str(skills_dir.resolve())
+    )
+
+
+def get_best_skill(prompt: str, skills_dir: Path, threshold: float = 0.7) -> dict:
+    if not prompt or not prompt.strip():
+        return _ok(None, 0.0)
+
+    active_skills_dir = _resolve_available_skills_dir(skills_dir)
+    if active_skills_dir is None:
+        return _ok(None, 0.0)
+
+    try:
+        if _needs_reindex(active_skills_dir):
+            index_skills(active_skills_dir)
+
+        payload = _load_cache_payload()
+        ids = payload.get("ids", [])
+        matrix = payload.get("matrix", None)
+
+        if not ids or matrix is None:
+            return _err("cache_data_empty")
+
+        matrix = np.asarray(matrix, dtype=np.float32)
+        if matrix.ndim != 2 or matrix.shape[0] == 0:
+            return _err("cache_matrix_invalid")
+
+        embedder = _get_embedder()
+        prompt_vec = np.asarray(list(embedder.embed([prompt]))[0], dtype=np.float32)
+
+        matrix_norm = matrix / (np.linalg.norm(matrix, axis=1, keepdims=True) + 1e-12)
+        prompt_norm = prompt_vec / (np.linalg.norm(prompt_vec) + 1e-12)
+        scores = matrix_norm @ prompt_norm
+
+        if scores.size == 0:
+            return _ok(None, 0.0)
+
+        best_idx = int(np.argmax(scores))
+        best_score = float(scores[best_idx])
+
+        if not np.isfinite(best_score) or best_score < float(threshold):
+            return _ok(None, 0.0)
+
+        return _ok(ids[best_idx], best_score)
+    except PermissionError:
+        return _err("cache_write_permission_denied")
+    except RuntimeError as exc:
+        return _err(str(exc))
+    except Exception as exc:  # pragma: no cover - defensive fallback
+        return _err(f"router_failure: {exc}")
+
+
+def main() -> int:
+    parser = JsonArgumentParser(add_help=True)
+    parser.add_argument("--prompt", default="", help="User text prompt")
+    parser.add_argument(
+        "--skills-dir",
+        default=".skills",
+        help="Path to skills directory",
+    )
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=0.7,
+        help="Cosine similarity threshold",
+    )
+
+    args = parser.parse_args()
+    skills_dir = Path(os.path.expanduser(args.skills_dir)).resolve()
+
+    result = get_best_skill(
+        prompt=args.prompt,
+        skills_dir=skills_dir,
+        threshold=args.threshold,
+    )
+    print(json.dumps(result, ensure_ascii=False))
+
+    return 0 if "error" not in result else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())