bluera-knowledge 0.36.0 → 0.37.0

package/scripts/eval-candidates.sh

@@ -0,0 +1,235 @@
+#!/usr/bin/env bash
+# Model Candidate Evaluation Script
+# Phase 1: Smoke test (load model, embed one query) — ~30s per model
+# Phase 2: Val benchmark (full real-v1-val dataset) — ~20-80min per model
+#
+# Usage:
+#   ./scripts/eval-candidates.sh              # Run all phases
+#   ./scripts/eval-candidates.sh --smoke-only  # Phase 1 only (fast)
+#   ./scripts/eval-candidates.sh --bench-only  # Phase 2 only (skip smoke, assume all pass)
+#   ./scripts/eval-candidates.sh --model gte-modernbert-base  # Test single model
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$PROJECT_DIR"
+
+RESULTS_DIR="$PROJECT_DIR/.bluera/bluera-knowledge/bench-data/model-eval"
+mkdir -p "$RESULTS_DIR"
+
+SMOKE_ONLY=false
+BENCH_ONLY=false
+SINGLE_MODEL=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --smoke-only) SMOKE_ONLY=true; shift ;;
+    --bench-only) BENCH_ONLY=true; shift ;;
+    --model) SINGLE_MODEL="$2"; shift 2 ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+# Priority-ordered candidate list
+CANDIDATES=(
+  "gte-modernbert-base"
+  "snowflake-arctic-embed-s"
+  "snowflake-arctic-embed-m-v1.5"
+  "jina-embeddings-v2-base-code"
+  "modernbert-embed-base"
+  "snowflake-arctic-embed-xs"
+  "snowflake-arctic-embed-m-v2.0"
+)
+
+if [[ -n "$SINGLE_MODEL" ]]; then
+  CANDIDATES=("$SINGLE_MODEL")
+fi
+
+SMOKE_PASSED=()
+SMOKE_FAILED=()
+
+# ============================================================
+# Phase 1: Smoke Tests
+# ============================================================
+smoke_test() {
+  local model_key="$1"
+  local result_file="$RESULTS_DIR/smoke-${model_key}.json"
+
+  echo -n "  [$model_key] Loading model... "
+
+  # Use bun to run inline TypeScript that loads model via our pipeline
+  local output
+  if output=$(timeout 120 bun -e "
+import { MODEL_REGISTRY } from './src/models/registry.ts';
+import { pipeline } from '@huggingface/transformers';
+
+const key = '${model_key}';
+const config = MODEL_REGISTRY[key];
+if (!config) {
+  console.error('Model not in registry: ' + key);
+  process.exit(1);
+}
+
+console.error('Downloading ' + config.id + '...');
+const start = Date.now();
+
+try {
+  const extractor = await pipeline('feature-extraction', config.id, { dtype: 'fp32' });
+
+  const testQuery = config.queryPrefix + 'How do I implement dependency injection?';
+  const result = await extractor(testQuery, { pooling: config.pooling, normalize: config.normalize });
+
+  const dims = result.dims;
+  const elapsed = Date.now() - start;
+  const sample = Array.from(result.data).slice(0, 3).map((v: number) => v.toFixed(4));
+
+  const report = {
+    model: key,
+    hfId: config.id,
+    status: 'pass',
+    dims: dims,
+    expectedDims: config.dimensions,
+    dimsMatch: JSON.stringify(dims) === JSON.stringify([1, config.dimensions]),
+    pooling: config.pooling,
+    sampleEmbedding: sample,
+    loadTimeMs: elapsed,
+    timestamp: new Date().toISOString(),
+  };
+  console.log(JSON.stringify(report));
+
+  await extractor.dispose();
+} catch (err: any) {
+  const report = {
+    model: key,
+    hfId: config.id,
+    status: 'fail',
+    error: err.message || String(err),
+    timestamp: new Date().toISOString(),
+  };
+  console.log(JSON.stringify(report));
+  process.exit(1);
+}
+" 2>"$RESULTS_DIR/smoke-${model_key}.log"); then
+    echo "$output" > "$result_file"
+    local dims load_time
+    dims=$(echo "$output" | bun -e "const d=JSON.parse(await Bun.stdin.text()); process.stdout.write(String(d.dims))")
+    load_time=$(echo "$output" | bun -e "const d=JSON.parse(await Bun.stdin.text()); process.stdout.write(String(d.loadTimeMs))")
+    echo "PASS (dims=${dims}, ${load_time}ms)"
+    return 0
+  else
+    echo "FAIL"
+    if [[ -f "$RESULTS_DIR/smoke-${model_key}.log" ]]; then
+      echo "    Error: $(tail -3 "$RESULTS_DIR/smoke-${model_key}.log")"
+    fi
+    return 1
+  fi
+}
+
+if [[ "$BENCH_ONLY" == "false" ]]; then
+  echo "========================================"
+  echo "Phase 1: Smoke Tests"
+  echo "========================================"
+  echo ""
+
+  for model in "${CANDIDATES[@]}"; do
+    if smoke_test "$model"; then
+      SMOKE_PASSED+=("$model")
+    else
+      SMOKE_FAILED+=("$model")
+    fi
+  done
+
+  echo ""
+  echo "----------------------------------------"
+  echo "Smoke Test Summary"
+  echo "----------------------------------------"
+  echo "Passed: ${#SMOKE_PASSED[@]}/${#CANDIDATES[@]}"
+  for m in "${SMOKE_PASSED[@]}"; do echo "  + $m"; done
+  if [[ ${#SMOKE_FAILED[@]} -gt 0 ]]; then
+    echo "Failed: ${#SMOKE_FAILED[@]}"
+    for m in "${SMOKE_FAILED[@]}"; do echo "  - $m"; done
+  fi
+  echo ""
+
+  if [[ "$SMOKE_ONLY" == "true" ]]; then
+    echo "Done (--smoke-only). To benchmark passing models:"
+    echo "  ./scripts/eval-candidates.sh --bench-only"
+    exit 0
+  fi
+else
+  # bench-only mode: assume all candidates pass smoke
+  SMOKE_PASSED=("${CANDIDATES[@]}")
+fi
+
+# ============================================================
+# Phase 2: Val Benchmarks
+# ============================================================
+if [[ ${#SMOKE_PASSED[@]} -eq 0 ]]; then
+  echo "No models passed smoke test. Nothing to benchmark."
+  exit 1
+fi
+
+echo "========================================"
+echo "Phase 2: Val Benchmarks (real-v1-val)"
+echo "========================================"
+echo "Models to benchmark: ${#SMOKE_PASSED[@]}"
+echo ""
+
+BENCH_RESULTS=()
+
+for model in "${SMOKE_PASSED[@]}"; do
+  echo "========================================"
+  echo "Benchmarking: $model"
+  echo "========================================"
+
+  local_artifact="$RESULTS_DIR/bench-${model}.json"
+
+  if BK_MODEL="$model" bun run bench:search \
+    --dataset real-v1-val \
+    --setup --force \
+    --artifacts "$local_artifact" 2>&1 | tee "$RESULTS_DIR/bench-${model}.log"; then
+    BENCH_RESULTS+=("$model")
+    echo ""
+    echo "  -> Artifact: $local_artifact"
+  else
+    echo "  -> BENCHMARK FAILED for $model"
+  fi
+  echo ""
+done
+
+# ============================================================
+# Phase 3: Comparison Summary
+# ============================================================
+echo "========================================"
+echo "COMPARISON SUMMARY"
+echo "========================================"
+echo ""
+
+# Extract key metrics from each artifact
+printf "%-35s %8s %8s %8s %8s %8s\n" "Model" "Hit@1" "MRR" "nDCG@10" "R@10" "P95ms"
+printf "%-35s %8s %8s %8s %8s %8s\n" "---" "---" "---" "---" "---" "---"
+
+for model in "${BENCH_RESULTS[@]}"; do
+  artifact="$RESULTS_DIR/bench-${model}.json"
+  if [[ -f "$artifact" ]]; then
+    bun -e "
+const data = JSON.parse(await Bun.file('${artifact}').text());
+const s = data.summary;
+const name = '${model}'.padEnd(35);
+const hit1 = (s.hitAt1 * 100).toFixed(1).padStart(7) + '%';
+const mrr = s.mrr.toFixed(3).padStart(8);
+const ndcg = (s.ndcgAt10 * 100).toFixed(1).padStart(7) + '%';
+const r10 = (s.recallAt10 * 100).toFixed(1).padStart(7) + '%';
+const p95 = s.latency.p95.toFixed(0).padStart(5) + 'ms';
+console.log(name + ' ' + hit1 + ' ' + mrr + ' ' + ndcg + ' ' + r10 + ' ' + p95);
+"
+  fi
+done
+
+# Also show champion baseline for reference
+echo ""
+echo "Champion baseline (bge-small-en-v1.5):"
+echo "  Hit@1=29.4% MRR=0.412 nDCG@10=46.0% R@10=45.1% P95=111ms"
+echo ""
+echo "Results saved to: $RESULTS_DIR/"

package/skills/advanced-workflows/references/combining-workflows.md

@@ -0,0 +1,17 @@
+# Combining Workflows
+
+Real-world usage often combines these patterns:
+
+```
+User: "I need to understand how Express and Hono handle middleware differently"
+
+1. list_stores() → check if both indexed
+2. If not: create_store() for missing framework(s)
+3. check_job_status() → wait for indexing
+4. search("middleware implementation", stores=['express', 'hono'], detail='minimal')
+5. Review summaries, identify key files
+6. get_full_context() for 2-3 most relevant from each framework
+7. Compare implementations with full context
+```
+
+This multi-step workflow is efficient, targeted, and conserves context.

package/skills/advanced-workflows/references/error-recovery.md

@@ -0,0 +1,44 @@
+# Error Recovery
+
+When operations fail, use these recovery patterns:
+
+### Workflow: Handle Indexing Failures
+
+```
+1. create_store() fails or job_status shows 'failed'
+   → Check error message
+   → Common issues:
+     - Git auth required (private repo)
+     - Invalid URL/path
+     - Disk space
+     - Network timeout
+
+2. Recovery actions:
+   - Auth issue: Provide credentials or use HTTPS
+   - Invalid path: Verify URL/path exists
+   - Disk space: delete_store() unused stores
+   - Network: Retry with smaller repo or use --shallow
+
+3. Verify recovery:
+   list_stores() → Check store appeared
+   search(test_query, stores=[new_store]) → Verify searchable
+```
+
+**Example:**
+
+```
+create_store('https://github.com/private/repo', 'my-repo')
+→ job_id: 'job_xyz'
+
+check_job_status('job_xyz')
+→ Status: failed
+→ Error: "Authentication required for private repository"
+
+# Recovery: Use authenticated URL or SSH
+create_store('git@github.com:private/repo.git', 'my-repo')
+→ job_id: 'job_xyz2'
+
+check_job_status('job_xyz2')
+→ Status: completed
+→ Success!
+```

package/skills/advanced-workflows/references/handling-large-results.md

@@ -0,0 +1,48 @@
+# Handling Large Result Sets
+
+When initial search returns many results, use progressive detail to avoid context overload:
+
+### Workflow: Progressive Detail Strategy
+
+```
+1. search(query, detail='minimal', limit=20)
+   → Get summaries only (~100 tokens/result)
+   → Review all 20 summaries quickly
+
+2. Filter by relevance score:
+   - Score > 0.8: Excellent match
+   - Score 0.6-0.8: Good match
+   - Score < 0.6: Possibly irrelevant
+
+3. For top 3-5 results (score > 0.7):
+   get_full_context(selected_ids)
+   → Fetch complete code only for relevant items
+   → Saves ~80% context vs fetching all upfront
+
+4. If nothing relevant:
+   search(refined_query, detail='contextual', limit=10)
+   → Try different query with more context
+   → Or broaden/narrow the search
+```
+
+**Example:**
+
+```
+# Initial broad search
+search("authentication middleware", detail='minimal', limit=20)
+→ 20 results, scores ranging 0.45-0.92
+→ Total context: ~2k tokens (minimal)
+
+# Filter by score
+Top results (>0.7):
+  - Result 3: auth/jwt.ts (score: 0.92)
+  - Result 7: middleware/authenticate.ts (score: 0.85)
+  - Result 12: auth/session.ts (score: 0.74)
+
+# Get full code for top 3 only
+get_full_context(['result_3', 'result_7', 'result_12'])
+→ Complete implementations for relevant files only
+→ Context: ~3k tokens (vs ~15k if we fetched all 20)
+
+# Found what we needed! If not, would refine query and retry.
+```

package/skills/advanced-workflows/references/multi-store-search.md

@@ -0,0 +1,42 @@
+# Multi-Store Search with Ranking
+
+When searching across multiple stores, use ranking to prioritize results:
+
+### Workflow: Cross-Library Search
+
+```
+1. search(query, limit=10)
+   → Searches ALL stores
+   → Returns mixed results ranked by relevance
+
+2. Review store distribution:
+   - If dominated by one store: might narrow to specific stores
+   - If balanced: good cross-library perspective
+
+3. For specific library focus:
+   search(query, stores=['lib1', 'lib2'], limit=15)
+   → Search only relevant libraries
+   → Get more results from target libraries
+```
+
+**Example:**
+
+User: "How do different frameworks handle routing?"
+
+```
+# Search all indexed frameworks
+search("routing implementation", intent='find-implementation', limit=15)
+→ Result mix:
+  - express (score: 0.91)
+  - fastapi (score: 0.89)
+  - hono (score: 0.87)
+  - vue-router (score: 0.82)
+  - ...
+
+# All stores represented, good comparative view!
+
+# If user wants deeper FastAPI focus:
+search("routing implementation", stores=['fastapi', 'starlette'], limit=20)
+→ More FastAPI/Starlette-specific results
+→ Deeper exploration of Python framework routing
+```

package/skills/search/statusline.md

@@ -0,0 +1,75 @@
+---
+description: Add bluera-knowledge status indicator to the statusline
+allowed-tools: [Read, Edit, Write, Bash]
+---
+
+# Bluera Knowledge Statusline
+
+Add a 📘 blue book icon with MCP connectivity LED to the Claude Code statusline.
+
+## What it shows
+
+- `📘●` (green) — MCP server process is running
+- `📘●` (red) — MCP server not detected
+
+## Instructions
+
+### 1. Check if already installed
+
+```bash
+grep -c "# --- bluera-knowledge ---" ~/.claude/statusline.sh 2>/dev/null
+```
+
+**If the count is >= 1: already installed.** Tell the user it's already present and stop. Do NOT inject again.
+
+**If 0 or file missing:** proceed to install.
+
+### 2. Read the current statusline
+
+```bash
+cat ~/.claude/statusline.sh
+```
+
+If the file doesn't exist, create a minimal statusline with just the BK module.
+
+### 3. Inject the module
+
+Read the module from the plugin:
+
+```bash
+cat "${CLAUDE_PLUGIN_ROOT:-.}/scripts/statusline-module.sh"
+```
+
+Insert the block between `# --- bluera-knowledge ---` and `# --- end bluera-knowledge ---` into `~/.claude/statusline.sh`:
+
+- Place the function **before** the final output `printf`/`echo` statement(s)
+- Place it **after** other module functions (like `get_bluera_status`, `get_project_type`, etc.)
+- The leading space in the printf output is intentional — it separates from the previous badge
+
+### 4. Wire into the output
+
+Find the output `printf` lines (there are typically 3 — one per context color threshold). Add `%s` and `"$BK_STATUS"` to each, positioned **after** `"$BLUERA_STATUS"` and **before** `"$GIT_INFO"`.
+
+For example, if the current format is:
+```bash
+printf "... %s%s%s ..." "$PROJECT_TYPE" "$BLUERA_STATUS" "$GIT_INFO" ...
+```
+
+Change to:
+```bash
+printf "... %s%s%s%s ..." "$PROJECT_TYPE" "$BLUERA_STATUS" "$BK_STATUS" "$GIT_INFO" ...
+```
+
+**Important:** Add exactly one `%s` to each format string AND one `"$BK_STATUS"` to each argument list. Count the format specifiers vs arguments to ensure they match.
+
+### 5. Verify
+
+```bash
+bash -n ~/.claude/statusline.sh && echo "Syntax OK"
+```
+
+### 6. Edge cases
+
+- **No statusline.sh exists**: Create a minimal one that reads stdin, runs `get_bk_status`, and echoes the result
+- **Non-bluera preset**: Find the output `echo`/`printf` and append `$BK_STATUS` to it
+- **No `$BLUERA_STATUS` in output**: Place `$BK_STATUS` at the end of the output, before any separators

package/skills/store-lifecycle/references/failure-recovery.md

@@ -0,0 +1,80 @@
+# Handling Indexing Failures
+
+### Common Failure Scenarios
+
+**1. Authentication Required (Private Repos)**
+```
+Error: "Authentication required"
+
+Fix options:
+  - Use SSH URL: git@github.com:org/repo.git
+  - Use HTTPS with token: https://token@github.com/org/repo.git
+  - Make repo public (if appropriate)
+```
+
+**2. Invalid URL/Path**
+```
+Error: "Repository not found" or "Path does not exist"
+
+Fix:
+  - Verify URL is correct (typos common!)
+  - Check path exists and is accessible
+  - Ensure network connectivity
+```
+
+**3. Disk Space**
+```
+Error: "No space left on device"
+
+Fix:
+  - Check available space: df -h
+  - Delete unused stores: delete_store(old_store)
+  - Clear .bluera/bluera-knowledge/repos/ manually if needed
+```
+
+**4. Network Timeout**
+```
+Error: "Connection timeout" or "Failed to fetch"
+
+Fix:
+  - Retry after checking network
+  - Use --shallow for large repos
+  - Clone manually then add-folder
+```
+
+**5. Unsupported File Types**
+```
+Warning: "Skipped 45 binary files"
+
+This is normal!
+  - Binary files (images, compiled code) are skipped
+  - Only text files are indexed
+  - Check indexed count vs total to see ratio
+```
+
+### Recovery Workflow
+
+```
+1. Attempt fails:
+   create_store(url, name) → job fails
+
+2. Check error:
+   job_status = check_job_status(job_id)
+   error_msg = job_status['error']
+
+3. Determine fix based on error type (see above)
+
+4. Retry with fix:
+   create_store(corrected_url, name)
+
+5. Verify success:
+   check_job_status(new_job_id)
+   → Status: completed
+
+   list_stores()
+   → Store appears in list
+
+6. Test search:
+   search(test_query, stores=[name], limit=3)
+   → Returns results: Ready to use!
+```

package/skills/store-lifecycle/references/indexing-strategies.md

@@ -0,0 +1,67 @@
+# Indexing Strategies
+
+### Initial Indexing
+
+When creating a store, indexing happens automatically in the background:
+
+```
+create_store(url, name)
+→ Returns: job_id
+→ Background: clone/download → analyze → index
+→ Status: pending → running → completed
+
+# Monitor progress
+check_job_status(job_id)
+→ Progress: 45% (processing src/core.ts)
+→ Estimated: ~2 minutes remaining
+```
+
+**Indexing time estimates:**
+- Small library (<1k files): 30-60 seconds
+- Medium library (1k-5k files): 1-3 minutes
+- Large library (>5k files): 3-10 minutes
+- Documentation crawl (100 pages): 1-2 minutes
+
+### Re-indexing (Updates)
+
+When library code changes or you modify indexed content:
+
+```
+# For git repos: pull latest changes
+cd .bluera/bluera-knowledge/repos/vue
+git pull origin main
+cd -
+
+# Re-index
+/bluera-knowledge:index vue
+
+# Or via MCP:
+index_store(store='vue')
+→ Re-processes all files
+→ Updates vector embeddings
+→ Rebuilds search index
+```
+
+**When to re-index:**
+- Library released new version
+- You modified local folder content
+- Search results seem outdated
+- After significant codebase changes
+
+**Re-indexing is incremental** - only changed files are re-processed.
+
+### Selective Indexing
+
+For large repos, you might want to index specific directories:
+
+```
+# Clone full repo manually
+git clone https://github.com/microsoft/vscode
+cd vscode
+
+# Index only specific dirs
+/bluera-knowledge:add-folder ./src/vs/editor --name=vscode-editor
+/bluera-knowledge:add-folder ./src/vs/workbench --name=vscode-workbench
+
+# Result: Multiple focused stores instead of one massive store
+```

package/skills/store-lifecycle/references/job-monitoring.md

@@ -0,0 +1,72 @@
+# Background Job Monitoring
+
+All expensive operations run as background jobs: cloning, indexing, crawling.
+
+### Job Lifecycle
+
+```
+1. create_store() or index_store() → Returns job_id
+
+2. Job states:
+   - pending: In queue, not started
+   - running: Actively processing
+   - completed: Finished successfully
+   - failed: Error occurred
+
+3. Monitor progress:
+   check_job_status(job_id)
+   → Current state, percentage, current file
+
+4. List all jobs:
+   list_jobs()
+   → See pending, running, completed jobs
+
+5. Cancel if needed:
+   cancel_job(job_id)
+   → Stops running job, cleans up
+```
+
+### Best Practices for Job Monitoring
+
+**Do poll, but not too frequently:**
+```
+# Too frequent - wastes resources
+while status != 'completed':
+    check_job_status(job_id)  # Every second!
+    sleep(1)
+
+# Reasonable polling interval
+while status != 'completed':
+    check_job_status(job_id)
+    sleep(15)  # Every 15 seconds is fine
+```
+
+**Do handle failures gracefully:**
+```
+status = check_job_status(job_id)
+
+if status['state'] == 'failed':
+    error = status['error']
+
+    if 'auth' in error.lower():
+        print("Authentication required - try SSH URL or provide credentials")
+    elif 'not found' in error.lower():
+        print("Repository/URL not found - check the source")
+    elif 'disk' in error.lower():
+        print("Disk space issue - delete unused stores")
+    else:
+        print(f"Unexpected error: {error}")
+```
+
+**Do list jobs to avoid duplicates:**
+```
+# Before creating new store
+jobs = list_jobs()
+existing = [j for j in jobs if j['store'] == 'vue' and j['state'] in ['pending', 'running']]
+
+if existing:
+    print(f"Job already running for 'vue': {existing[0]['id']}")
+    # Wait for it instead of creating duplicate
+else:
+    create_store(...)
+```