claude-local-docs 1.0.2 → 1.0.12

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-local-docs",
-  "version": "1.0.2",
-  "description": "Local-first Context7 alternative — indexes JS/TS dependency docs with a 4-stage RAG pipeline. All models run locally via ONNX.",
+  "version": "1.0.12",
+  "description": "Local-first Context7 alternative — indexes JS/TS dependency docs with a 4-stage RAG pipeline. Uses TEI (Text Embeddings Inference) Docker containers for embeddings and reranking.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -10,14 +10,20 @@
   "files": [
     "dist",
     "commands",
+    "hooks",
+    "scripts",
     ".claude-plugin",
     ".mcp.json",
+    "docker-compose.yml",
+    "docker-compose.nvidia.yml",
+    "start-tei.sh",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "test": "tsc && node --test dist/integration.test.js",
     "prepublishOnly": "tsc"
   },
   "keywords": [
@@ -34,18 +40,23 @@
   ],
   "author": "matthew",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/matteodante/claude-local-docs.git"
   },
   "dependencies": {
-    "@huggingface/transformers": "^3.4.1",
     "@lancedb/lancedb": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "turndown": "^7.2.2",
+    "turndown-plugin-gfm": "^1.0.2",
     "zod": "^3.24.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/turndown": "^5.0.6",
     "esbuild": "^0.27.3",
     "typescript": "^5.7.0"
   }

package/scripts/ensure-tei.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# ensure-tei.sh — SessionStart hook: check if TEI containers are running, start if not.
+# This script is idempotent and fast when containers are already up.
+#
+# Output: JSON with additionalContext for Claude's context window.
+
+set -euo pipefail
+
+PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+# ── Check if Docker is available ─────────────────────────────────────
+if ! command -v docker &>/dev/null; then
+  cat <<'EOF'
+{"additionalContext": "WARNING: Docker is not installed. TEI inference containers are not running. The search_docs and store_and_index_doc tools will fail. Install Docker Desktop from https://www.docker.com/products/docker-desktop/ and run ./start-tei.sh to start the TEI containers."}
+EOF
+  exit 0
+fi
+
+if ! docker info &>/dev/null 2>&1; then
+  cat <<'EOF'
+{"additionalContext": "WARNING: Docker daemon is not running. TEI inference containers are not available. Start Docker Desktop, then run ./start-tei.sh to start the TEI containers."}
+EOF
+  exit 0
+fi
+
+# ── Check if TEI containers are already healthy ──────────────────────
+embed_ok=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:39281/health 2>/dev/null || echo "000")
+rerank_ok=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:39282/health 2>/dev/null || echo "000")
+
+if [ "$embed_ok" = "200" ] && [ "$rerank_ok" = "200" ]; then
+  cat <<'EOF'
+{"additionalContext": "TEI inference containers are running and healthy (embed :39281, rerank :39282)."}
+EOF
+  exit 0
+fi
+
+# ── Check if native TEI (Metal) is running via PID file ──────────────
+if [ -f "$PLUGIN_DIR/.tei-pids" ]; then
+  all_alive=true
+  while IFS= read -r pid; do
+    if ! kill -0 "$pid" 2>/dev/null; then
+      all_alive=false
+      break
+    fi
+  done < "$PLUGIN_DIR/.tei-pids"
+
+  if $all_alive; then
+    # PIDs alive but health check failed — still starting up, don't restart
+    cat <<'EOF'
+{"additionalContext": "TEI native processes are running but not yet healthy. They may still be loading models. Wait a moment and try again."}
+EOF
+    exit 0
+  fi
+fi
+
+# ── Try to start containers ──────────────────────────────────────────
+if [ -f "$PLUGIN_DIR/start-tei.sh" ]; then
+  echo "Starting TEI containers..." >&2
+  bash "$PLUGIN_DIR/start-tei.sh" >&2 2>&1 && {
+    cat <<'EOF'
+{"additionalContext": "TEI inference containers started successfully (embed :39281, rerank :39282). Ready for indexing and search."}
+EOF
+    exit 0
+  }
+fi
+
+# ── Fallback: containers not running, can't auto-start ───────────────
+cat <<'EOF'
+{"additionalContext": "WARNING: TEI inference containers are not running. Run ./start-tei.sh in the claude-local-docs plugin directory to start them. Without TEI, search_docs and store_and_index_doc will fail."}
+EOF
+exit 0

package/start-tei.sh

@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+# start-tei.sh — Auto-detect GPU and start TEI with the optimal backend.
+#
+# Usage:
+#   ./start-tei.sh            # auto-detect (NVIDIA GPU → Docker, Apple Silicon → Metal native, else CPU Docker)
+#   ./start-tei.sh --metal    # force native Metal build (macOS Apple Silicon)
+#   ./start-tei.sh --cpu      # force CPU Docker
+#   ./start-tei.sh --tag 89-1.9  # force a specific TEI Docker image tag
+#   ./start-tei.sh --stop     # stop all running TEI (Docker + native)
+#
+# NVIDIA architecture → optimized TEI Docker image:
+#   12.x  Blackwell  RTX 50x0          → 120-1.9
+#   10.x  Blackwell  B200              → 100-1.9  (experimental)
+#    9.x  Hopper     H100/H200         → hopper-1.9
+#    8.9  Ada        RTX 40x0 / L4     → 89-1.9
+#    8.6  Ampere     RTX 30x0 / A10    → 86-1.9
+#    8.0  Ampere     A100              → 1.9
+#    7.5  Turing     T4 / RTX 20x0    → turing-1.9 (experimental)
+#    *    fallback                      → cuda-1.9
+#
+# Apple Silicon → native Metal build via cargo (no Docker)
+
+set -euo pipefail
+cd "$(dirname "$0")"
+
+PID_FILE=".tei-pids"
+TEI_REPO="https://github.com/huggingface/text-embeddings-inference"
+TEI_CLONE_DIR="${TEI_CLONE_DIR:-/tmp/text-embeddings-inference}"
+
+# ── Arg parsing ──────────────────────────────────────────────────────
+MODE=""         # auto | metal | cpu | tag | stop
+FORCE_TAG=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --metal) MODE="metal"; shift ;;
+    --cpu)   MODE="cpu"; shift ;;
+    --tag)   MODE="tag"; FORCE_TAG="$2"; shift 2 ;;
+    --stop)  MODE="stop"; shift ;;
+    *)       echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+[ -z "$MODE" ] && MODE="auto"
+
+# ── Stop all TEI processes ───────────────────────────────────────────
+stop_tei() {
+  local stopped=false
+
+  # Stop native processes
+  if [ -f "$PID_FILE" ]; then
+    echo "Stopping native TEI processes..."
+    while IFS= read -r pid; do
+      if kill -0 "$pid" 2>/dev/null; then
+        kill "$pid" 2>/dev/null || true
+        stopped=true
+      fi
+    done < "$PID_FILE"
+    rm -f "$PID_FILE"
+  fi
+
+  # Stop Docker containers
+  if docker compose -f docker-compose.yml -f docker-compose.nvidia.yml ps -q 2>/dev/null | grep -q .; then
+    echo "Stopping Docker TEI containers..."
+    docker compose -f docker-compose.yml -f docker-compose.nvidia.yml down 2>/dev/null || true
+    stopped=true
+  elif docker compose ps -q 2>/dev/null | grep -q .; then
+    echo "Stopping Docker TEI containers..."
+    docker compose down 2>/dev/null || true
+    stopped=true
+  fi
+
+  if $stopped; then
+    echo "Stopped."
+  else
+    echo "No running TEI processes found."
+  fi
+}
+
+if [ "$MODE" = "stop" ]; then
+  stop_tei
+  exit 0
+fi
+
+# Stop any existing TEI before starting new ones
+stop_tei 2>/dev/null || true
+
+# ── Detect best TEI tag for NVIDIA GPU ───────────────────────────────
+detect_nvidia_tag() {
+  local cc major minor
+  cc=$(nvidia-smi --query-gpu=compute_cap --format=csv,noheader 2>/dev/null | head -1 | tr -d '[:space:]') || return 1
+  [ -z "$cc" ] && return 1
+
+  major="${cc%%.*}"
+  minor="${cc#*.}"
+
+  case "$major" in
+    12) echo "120-1.9" ;;      # Blackwell RTX 50x0
+    10) echo "100-1.9" ;;      # Blackwell B200
+     9) echo "hopper-1.9" ;;   # Hopper
+     8) case "$minor" in
+          9) echo "89-1.9" ;;  # Ada Lovelace
+          6) echo "86-1.9" ;;  # Ampere A10/A40
+          0) echo "1.9" ;;     # Ampere A100
+          *) echo "cuda-1.9" ;;
+        esac ;;
+     7) echo "turing-1.9" ;;   # Turing
+     *) echo "cuda-1.9" ;;     # Unknown — generic CUDA
+  esac
+}
+
+# ── Metal: native macOS build ────────────────────────────────────────
+start_metal() {
+  local TEI_BIN
+  TEI_BIN=$(command -v text-embeddings-router 2>/dev/null || echo "")
+
+  if [ -z "$TEI_BIN" ]; then
+    echo "text-embeddings-router not found. Building with Metal support..."
+
+    if ! command -v cargo &>/dev/null; then
+      echo "Error: Rust is required. Install from https://rustup.rs"
+      exit 1
+    fi
+
+    if [ -d "$TEI_CLONE_DIR" ]; then
+      echo "Updating TEI source..."
+      git -C "$TEI_CLONE_DIR" pull --ff-only
+    else
+      echo "Cloning TEI..."
+      git clone "$TEI_REPO" "$TEI_CLONE_DIR"
+    fi
+
+    echo "Building text-embeddings-router with Metal (this may take a few minutes)..."
+    cargo install --path "$TEI_CLONE_DIR/router" --features metal
+    TEI_BIN=$(command -v text-embeddings-router)
+  fi
+
+  echo "┌─────────────────────────────────────────────┐"
+  echo "│  Backend: Metal (native macOS)"
+  echo "│  Binary:  $TEI_BIN"
+  echo "└─────────────────────────────────────────────┘"
+
+  rm -f "$PID_FILE"
+
+  echo "Starting TEI embed (Metal) on :39281..."
+  "$TEI_BIN" --model-id nomic-ai/nomic-embed-text-v1.5 --port 39281 --max-client-batch-size 64 &
+  echo $! >> "$PID_FILE"
+
+  echo "Starting TEI rerank (Metal) on :39282..."
+  "$TEI_BIN" --model-id cross-encoder/ms-marco-MiniLM-L-6-v2 --port 39282 &
+  echo $! >> "$PID_FILE"
+
+  wait_for_health
+}
+
+# ── Docker: NVIDIA or CPU ────────────────────────────────────────────
+start_docker() {
+  local COMPOSE_FILES=("-f" "docker-compose.yml")
+  local GPU_NAME=""
+  local TEI_TAG
+
+  if [ "$MODE" = "tag" ]; then
+    TEI_TAG="$FORCE_TAG"
+    if [[ "$TEI_TAG" != cpu-* ]]; then
+      COMPOSE_FILES+=("-f" "docker-compose.nvidia.yml")
+    fi
+  elif [ "$MODE" = "cpu" ]; then
+    TEI_TAG="cpu-1.9"
+  elif command -v nvidia-smi &>/dev/null; then
+    local TAG
+    TAG=$(detect_nvidia_tag) || TAG=""
+    if [ -n "$TAG" ]; then
+      TEI_TAG="$TAG"
+      GPU_NAME=$(nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null | head -1 | xargs)
+      COMPOSE_FILES+=("-f" "docker-compose.nvidia.yml")
+    else
+      TEI_TAG="cpu-1.9"
+    fi
+  else
+    TEI_TAG="cpu-1.9"
+  fi
+
+  export TEI_TAG
+
+  echo "┌─────────────────────────────────────────────┐"
+  if [ -n "$GPU_NAME" ]; then
+    echo "│  GPU:      $GPU_NAME"
+  fi
+  echo "│  Backend:  Docker"
+  echo "│  Tag:      $TEI_TAG"
+  echo "│  Compose:  ${COMPOSE_FILES[*]}"
+  echo "└─────────────────────────────────────────────┘"
+
+  docker compose "${COMPOSE_FILES[@]}" up -d
+
+  wait_for_health
+}
+
+# ── Health check loop ────────────────────────────────────────────────
+wait_for_health() {
+  echo ""
+  echo "Waiting for TEI to be ready..."
+  for i in $(seq 1 120); do
+    embed=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:39281/health 2>/dev/null || true)
+    rerank=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:39282/health 2>/dev/null || true)
+    if [ "$embed" = "200" ] && [ "$rerank" = "200" ]; then
+      printf "\n"
+      echo "Ready! embed=OK rerank=OK"
+      return 0
+    fi
+    printf "\r  [%3d] embed=%s rerank=%s" "$i" "$embed" "$rerank"
+    sleep 3
+  done
+
+  printf "\n"
+  echo "Warning: TEI did not become healthy within 6 minutes."
+  return 1
+}
+
+# ── Main ─────────────────────────────────────────────────────────────
+case "$MODE" in
+  metal)
+    start_metal
+    ;;
+  auto)
+    # Auto-detect: NVIDIA → Docker GPU, Apple Silicon → Metal native, else → Docker CPU
+    if command -v nvidia-smi &>/dev/null && nvidia-smi &>/dev/null; then
+      start_docker
+    elif [[ "$(uname -s)" == "Darwin" ]] && [[ "$(uname -m)" == "arm64" ]]; then
+      echo "Detected Apple Silicon — using native Metal backend"
+      start_metal
+    else
+      start_docker
+    fi
+    ;;
+  *)
+    start_docker
+    ;;
+esac