pi-skill-search 0.1.0

package/src/categories.ts

@@ -0,0 +1,383 @@
+/**
+ * Category classifier — phan loai skill theo category.
+ * Implement theo SPEC §6.1 rules va §6.2 logic.
+ *
+ * Luu y: Word-boundary matching cho single-word keywords de tranh false positives.
+ * Multi-word keywords (phrases) match exact substring.
+ */
+export interface CategoryRule {
+	name: string;
+	keywords: string[];
+	maxExamples: number;
+}
+
+/**
+ * 14 category rules tu SPEC §6.1.
+ * Thu tu khai bao quyet dinh thu tu trong summary output.
+ */
+export const CATEGORY_RULES: CategoryRule[] = [
+	{
+		name: "Cheminformatics & Drug Discovery",
+		keywords: [
+			"molecular",
+			"molecule",
+			"drug",
+			"compound",
+			"chemic",
+			"smiles",
+			"docking",
+			"fingerprint",
+			"admet",
+			"cheminformatics",
+			"medicinal",
+			"rdkit",
+			"virtual screening",
+			"lead optim",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "Bioinformatics & Genomics",
+		keywords: [
+			"gene",
+			"genomic",
+			"rna-seq",
+			"single-cell",
+			"transcriptom",
+			"protein",
+			"sequence",
+			"variant",
+			"alignment",
+			"phylogen",
+			"pathway",
+			"gene regul",
+			"anndata",
+			"h5ad",
+			"neural recording",
+			"neuropixel",
+			"spikeglx",
+			"openephys",
+			"electrophysiolog",
+			"cytometry",
+			"imaging",
+			"radiology",
+			"pathology",
+			"knowledge graph",
+			"microscopy",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "Machine Learning & AI",
+		keywords: [
+			"machine learning",
+			"deep learning",
+			"neural network",
+			"reinforcement learn",
+			"gradient boost",
+			"random forest",
+			"model train",
+			"pytorch",
+			"tensorflow",
+			"transformer",
+			"gan",
+			"cnn",
+			"rnn",
+			"lstm",
+			"interpret",
+			"shap",
+			"feature engineer",
+			"scikit",
+			"sklearn",
+			"quantum comput",
+			"probabilistic",
+			"bayesian",
+			"mcmc",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "Clinical & Medical",
+		keywords: [
+			"clinical",
+			"patient",
+			"medical",
+			"diagnosis",
+			"treatment",
+			"ehr",
+			"electronic health",
+			"hospital",
+			"therap",
+			"trial",
+			"icd",
+			"hipaa",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "Data Visualization & EDA",
+		keywords: [
+			"visualization",
+			"plotting",
+			"chart",
+			"datafram",
+			"eda",
+			"network analysis",
+			"time series",
+			"forecast",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "Scientific Writing & Communication",
+		keywords: [
+			"writing",
+			"paper",
+			"publication",
+			"peer review",
+			"citation",
+			"bibtex",
+			"literature",
+			"poster",
+			"slide",
+			"schematic",
+			"infographic",
+			"markdown",
+			"document convert",
+			"report",
+			"research proposal",
+			"latex",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "Geospatial & Remote Sensing",
+		keywords: [
+			"geospatial",
+			"gis",
+			"satellite",
+			"spatial",
+			"terrain",
+			"remote sensing",
+			"raster",
+			"vector",
+			"coordinate",
+			"map",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "Lab Automation & Integration",
+		keywords: [
+			"lab",
+			"laboratory",
+			"liquid handl",
+			"plate reader",
+			"workflow automat",
+			"lims",
+			"pipette",
+			"robot",
+			"opentrons",
+			"benchling",
+			"latchbio",
+			"microscopy",
+			"hpc",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "Time Series & Forecasting",
+		keywords: ["time series", "forecast", "anomaly detect", "signal process", "timesfm", "aeon"],
+		maxExamples: 5,
+	},
+	{
+		name: "Materials Science & Engineering",
+		keywords: [
+			"crystal",
+			"material",
+			"phase diagram",
+			"metabolic model",
+			"simulation",
+			"optimization",
+			"pymoo",
+			"simpy",
+			"pymatgen",
+			"fluid dynamics",
+			"navier-stokes",
+			"turbulence",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "Research Methodology",
+		keywords: [
+			"hypothesis",
+			"brainstorm",
+			"critical thinking",
+			"grant",
+			"scholar",
+			"peer review",
+			"reproducib",
+			"experimental design",
+			"nsf",
+			"nih",
+			"doe",
+			"darpa",
+			"proposal",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "Integration Platforms",
+		keywords: [
+			"benchling",
+			"modal",
+			"streamlit",
+			"gradio",
+			"api",
+			"rest",
+			"webhook",
+			"service",
+			"deploy",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "Developer Tools & Workflow",
+		keywords: [
+			"debug",
+			"profile",
+			"test",
+			"ci/cd",
+			"lint",
+			"format",
+			"types",
+			"version control",
+			"repo",
+			"github",
+		],
+		maxExamples: 5,
+	},
+	{
+		name: "AI Agent & Pi Extensions",
+		keywords: [
+			"agent",
+			"crew",
+			"team",
+			"worker",
+			"pipeline",
+			"memory",
+			"pi-extension",
+			"extension",
+			"pi-skill",
+			"pi extension",
+			"skill",
+			"llm",
+			"prompt",
+			"task",
+			"orchestrat",
+			"async",
+			"parallel",
+			"pi-crew",
+			"pi crew",
+			"autonomous",
+			"react-agent",
+			"react agent",
+			"codegen",
+			"code generat",
+			"browser-agent",
+			"browser agent",
+			"langchain",
+			"langgraph",
+			"crewai",
+			"ultraqa",
+			"ultragoal",
+			"omc ",
+			"claude mem",
+			"deep-interview",
+			"deep interview",
+			"deepinit",
+			"deep codebase",
+			"learner",
+			"make-plan",
+			"make plan",
+			"mcp",
+			"code review",
+			"pull request",
+			"subagent",
+			"dispatching",
+			"executing plan",
+			"verification-before",
+			"systematic debug",
+			"semantic compress",
+			"smart-explore",
+			"smart explore",
+			"consciousness",
+			"hud",
+			"autoresearch",
+			"self-improve",
+			"babysit",
+			"writer-memory",
+			"writer memory",
+			"visual-verdict",
+			"visual verdict",
+			"external-context",
+			"external context",
+			"remember",
+			"system prompt",
+			"spec-kit",
+			"community extension",
+			"verify",
+			"plan",
+			"finishing",
+			"development branch",
+			"learn-codebase",
+			"semantic-compression",
+			"systematic-debugging",
+		],
+		maxExamples: 5,
+	},
+];
+
+/**
+ * Phan loai skill vao cac categories.
+ * Word-boundary matching: keyword phai la mot "word" trong text.
+ * Multi-word keywords (phrases) phai xuat hien exactly trong text.
+ * Gioi han false positives nhu "gene" matching "generation".
+ */
+export function classify(entry: { name: string; description: string }): string[] {
+	const text = `${entry.name} ${entry.description}`.toLowerCase();
+	const matched: string[] = [];
+
+	for (const rule of CATEGORY_RULES) {
+		if (rule.keywords.some((kw) => matchKeyword(kw, text))) {
+			matched.push(rule.name);
+		}
+	}
+
+	return matched.length > 0 ? matched : ["Other"];
+}
+
+/**
+ * Match keyword trong text voi word-boundary semantics.
+ * - Single-word keyword: phai la mot "word" (bounded boi non-alphanumeric/start/end)
+ * - Multi-word keyword: phai xuat hien exactly trong text
+ */
+function matchKeyword(keyword: string, text: string): boolean {
+	const kw = keyword.toLowerCase();
+	if (kw.includes(" ")) {
+		// Multi-word: exact substring match
+		return text.includes(kw);
+	}
+	// Single-word: word boundary match
+	// Match: bounded by non-alphanumeric or start/end
+	const pattern = new RegExp(`(?:[^a-z0-9]|^)${escapeRegex(kw)}(?:[^a-z0-9]|$)`, "i");
+	return pattern.test(text);
+}
+
+/**
+ * Escape regex special characters.
+ */
+function escapeRegex(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/format.ts

@@ -0,0 +1,104 @@
+/**
+ * Output formatters — render category summary, tool description, search results.
+ * Implement theo SPEC §4.4, §4.5, §6.3.
+ */
+import type { SearchResult, SkillIndex } from "./types.ts";
+
+/**
+ * Uong tinh token count (chars / 3.5).
+ */
+export function estimateTokens(text: string): number {
+	return Math.ceil(text.length / 3.5);
+}
+
+/**
+ * Render category summary cho system prompt.
+ * SPEC §6.3 format voi token budget enforcement (≤250 tokens).
+ */
+export function formatCategorySummary(index: SkillIndex): string {
+	// Render voi progressive truncation: maxExamples 5 → 4 → 3 → 2 → 1 → 0
+	for (let maxEx = 5; maxEx >= 0; maxEx--) {
+		const summary = renderSummary(index, maxEx);
+		if (estimateTokens(summary) <= 250) {
+			return summary;
+		}
+	}
+	// Fallback: chi category names
+	return renderCategoryNamesOnly(index);
+}
+
+/**
+ * Render summary voi specific maxExamples.
+ */
+function renderSummary(index: SkillIndex, maxExamples: number): string {
+	const lines: string[] = ["## Available Skill Domains", ""];
+
+	for (const cat of index.categories) {
+		const examples = cat.examples.slice(0, maxExamples);
+		const exStr = examples.length > 0 ? ` (${examples.join(", ")})` : "";
+		lines.push(`- **${cat.name}**: ${cat.count} skills${exStr}`);
+	}
+
+	lines.push("");
+	lines.push("Use the `skill-search` tool to find specific skills by keyword.");
+
+	return lines.join("\n");
+}
+
+/**
+ * Render chi category names khi summary vuot token budget.
+ */
+function renderCategoryNamesOnly(index: SkillIndex): string {
+	const names = index.categories.map((c) => c.name).join(", ");
+	return `## Available Skill Domains\n\n${names}\n\nUse the \`skill-search\` tool to find specific skills.`;
+}
+
+/**
+ * Render tool description voi live category list.
+ * SPEC §4.4 template.
+ */
+export function renderToolDescription(index: SkillIndex): string {
+	const categoryList = index.categories.map((c) => c.name.toLowerCase()).join(", ");
+
+	// Top 3 categories by count (ties by declaration order)
+	const sorted = [...index.categories].sort((a, b) => {
+		if (b.count !== a.count) return b.count - a.count;
+		return index.categories.indexOf(a) - index.categories.indexOf(b);
+	});
+
+	const top3 = sorted.slice(0, 3);
+	const examples = top3
+		.filter((c) => c.examples.length > 0)
+		.map((c) => `"${c.examples[0]}"`)
+		.join(", ");
+
+	return [
+		"Search for skills by keyword. Returns top matching skills with name, description, and path.",
+		`Available domains: ${categoryList}.`,
+		`Try queries like: ${examples}.`,
+		"Use the `read` tool to load a skill's full SKILL.md after finding it.",
+	].join(" ");
+}
+
+/**
+ * Format search results cho tool output.
+ * SPEC §4.3 format.
+ */
+export function formatResults(query: string, results: SearchResult[], totalIndexed: number): string {
+	if (results.length === 0) {
+		return `No skills found matching '${query}'. ${totalIndexed} skills indexed. Try broader terms.`;
+	}
+
+	const lines: string[] = [`Found ${results.length} skills for "${query}":`, ""];
+
+	for (const r of results) {
+		lines.push(`## ${r.name} (score: ${r.score.toFixed(2)})`);
+		lines.push(r.description);
+		lines.push(`Path: ${r.path}`);
+		lines.push("");
+	}
+
+	lines.push("Use the `read` tool to load a skill's full instructions from the path above.");
+
+	return lines.join("\n");
+}

package/src/indexer.ts

@@ -0,0 +1,101 @@
+import { CATEGORY_RULES, classify } from "./categories.ts";
+import { tokenize } from "./text.ts";
+/**
+ * Index builder — buildIndex va fingerprintSkills.
+ * Implement theo SPEC §6.4.
+ */
+import type { CategorySummary, PiSkill, SkillEntry, SkillIndex } from "./types.ts";
+
+/**
+ * Build search index tu danh sach Pi skills.
+ * Two-pass algorithm per SPEC §6.4:
+ *   Pass 1: classify + tokenize moi skill
+ *   Pass 2: build CategorySummary[] theo CATEGORY_RULES declaration order
+ *
+ * Deterministic: cung input → cung output (last-write-wins nameIndex).
+ */
+export function buildIndex(skills: PiSkill[]): SkillIndex {
+	const entries = new Map<string, SkillEntry>();
+	const nameIndex = new Map<string, string>();
+
+	// Pass 1: build entries
+	for (const skill of skills) {
+		const categories = classify(skill);
+		const nameTokens = tokenize(skill.name);
+		const descTokens = tokenize(skill.description);
+
+		const entry: SkillEntry = {
+			name: skill.name,
+			description: skill.description,
+			path: skill.filePath,
+			categories,
+			nameTokens,
+			descTokens,
+		};
+
+		entries.set(skill.name, entry);
+
+		// Build nameIndex: tokenized name fragment → skill name
+		for (const token of nameTokens) {
+			nameIndex.set(token, skill.name);
+		}
+	}
+
+	// Pass 2: build CategorySummary[] in CATEGORY_RULES declaration order
+	const categoryMap = new Map<string, string[]>();
+
+	// Khoi tao tat ca categories theo declaration order
+	for (const rule of CATEGORY_RULES) {
+		categoryMap.set(rule.name, []);
+	}
+
+	// Phan bo skills vao categories
+	for (const entry of entries.values()) {
+		for (const cat of entry.categories) {
+			const list = categoryMap.get(cat);
+			if (list) {
+				list.push(entry.name);
+			} else {
+				// "Other" — khong co trong CATEGORY_RULES
+				categoryMap.set(cat, [entry.name]);
+			}
+		}
+	}
+
+	// Build CategorySummary[] — chi bao gom categories co skills
+	const categories: CategorySummary[] = [];
+
+	for (const rule of CATEGORY_RULES) {
+		const skills = categoryMap.get(rule.name);
+		if (skills && skills.length > 0) {
+			categories.push({
+				name: rule.name,
+				count: skills.length,
+				examples: skills.slice(0, rule.maxExamples),
+			});
+		}
+	}
+
+	// Them "Other" cuoi cung neu co
+	const otherSkills = categoryMap.get("Other");
+	if (otherSkills && otherSkills.length > 0) {
+		categories.push({
+			name: "Other",
+			count: otherSkills.length,
+			examples: otherSkills.slice(0, 5),
+		});
+	}
+
+	return { entries, categories, nameIndex };
+}
+
+/**
+ * Tao fingerprint tu danh sach skills de detect thay doi.
+ * Sorted filePath join — deterministic.
+ */
+export function fingerprintSkills(skills: PiSkill[]): string {
+	return skills
+		.map((s) => `${s.filePath}:${s.name}:${s.description.length}:${s.disableModelInvocation ? 1 : 0}`)
+		.sort()
+		.join("\n");
+}

package/src/proactive.ts

@@ -0,0 +1,51 @@
+/**
+ * Phase 10 — Proactive suggestion hook.
+ * Detect Python package imports trong bash commands va suggest matching skills.
+ * SPEC §11 E02-S01.
+ */
+
+/**
+ * Regex patterns cho detecting Python package imports/installs.
+ */
+const PATTERNS = [
+	{ re: /\bimport\s+([a-zA-Z_][\w]*)/g, multi: false },
+	{ re: /\bfrom\s+([a-zA-Z_][\w]*)\s+import\b/g, multi: false },
+	{ re: /\bpip\s+install\s+(.+)/g, multi: true },
+	{ re: /\buv\s+(?:add|pip\s+install)\s+(.+)/g, multi: true },
+];
+
+/**
+ * Detect Python package names tu bash command.
+ * Tra ve danh sach package names da detect.
+ */
+export function detectPythonPackages(command: string): string[] {
+	const packages = new Set<string>();
+
+	// Skip comments
+	if (command.trim().startsWith("#")) return [];
+
+	for (const { re, multi } of PATTERNS) {
+		const regex = new RegExp(re.source, re.flags);
+		let match: RegExpExecArray | null = regex.exec(command);
+		while (match !== null) {
+			if (multi) {
+				// Split by whitespace, filter out flags like -r, -U, etc
+				const parts = match[1].split(/\s+/);
+				for (const part of parts) {
+					const pkg = part.split(/[=><@]/)[0].trim();
+					if (pkg && pkg.length >= 2 && !pkg.startsWith("-")) {
+						packages.add(pkg.toLowerCase());
+					}
+				}
+			} else {
+				const pkg = match[1].split(/[=><@]/)[0].trim();
+				if (pkg && pkg.length >= 2) {
+					packages.add(pkg.toLowerCase());
+				}
+			}
+			match = regex.exec(command);
+		}
+	}
+
+	return [...packages];
+}