@pi-unipi/cocoindex 2.0.0

package/skills/cocoindex/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: cocoindex
+description: "CocoIndex content indexing and search — use when you need to search indexed project content or trigger re-indexing"
+---
+
+# CocoIndex Skill
+
+## When to Use CocoIndex
+
+Use CocoIndex tools and commands when you need to:
+
+1. **Search indexed project content** — use `cocoindex_search` instead of `content_search` or `ctx_search`
+2. **Trigger re-indexing** — use `/unipi:cocoindex-update` after significant code changes
+3. **Initialize indexing** — use `/unipi:cocoindex-init` for new projects
+
+## Key Differences from Old FTS5 Content Store
+
+| Aspect | Old (FTS5) | New (CocoIndex) |
+|--------|-----------|-----------------|
+| Chunking | Heading/paragraph split | AST-aware code, recursive text |
+| Search | BM25 + trigram fuzzy | Semantic vector + full-text |
+| Incremental | Full re-index every time | Delta-only (changed files) |
+| Scale | Small corpus | Multi-GiB, parallel |
+| Store | SQLite FTS5 | LanceDB |
+
+## Tools
+
+### `cocoindex_search`
+Search indexed content. It uses semantic vector search when the LanceDB table has vectors, LanceDB full-text search when an inverted index exists, and a lexical fallback for older text-only indexes.
+
+```
+cocoindex_search({ query: "how authentication works", limit: 10 })
+```
+
+Returns results with `title`, `content`, `source`, `rank`, `contentType`, and `matchLayer`.
+
+### `cocoindex_status`
+Check indexing status — pipeline configured, last run, doc count, CLI availability.
+
+```
+cocoindex_status({})
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unipi:cocoindex-update` | Run `cocoindex update` on current project |
+| `/unipi:cocoindex-status` | Show indexing status |
+| `/unipi:cocoindex-init` | Scaffold a default pipeline |
+| `/unipi:cocoindex-search <query>` | Search indexed codebase semantically |
+| `/unipi:cocoindex-settings` | Show configuration |
+
+## Prerequisites
+
+1. **Python 3.10+** with `cocoindex` installed:
+   ```bash
+   pip install cocoindex
+   pip install 'cocoindex[lancedb]'
+   ```
+
+2. **Pipeline initialized** — run `/unipi:cocoindex-init` once per project
+
+3. **Embedding config** — CocoIndex reuses the memory package's embedding settings:
+   - API key from `~/.unipi/memory/config.json`
+   - Same model and dimensions for cross-system search
+
+## Architecture
+
+```
+Project files → LocalFile source → SplitRecursively → EmbedText → LanceDB
+                                                                              ↓
+Agent query ──────────────────────────────→ vector search → ranked results
+```
+
+- Pipeline defined in `.unipi/cocoindex/main.py` (auto-generated, customizable)
+- Data stored in `.unipi/cocoindex/.lancedb/`
+- Search queries LanceDB directly via Node.js SDK (no CLI round-trip)
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| "CLI not found" | `pip install cocoindex` |
+| "Pipeline not initialized" | `/unipi:cocoindex-init` |
+| "Search unavailable" | `npm install @lancedb/lancedb` |
+| "No results" | Run `/unipi:cocoindex-update` first |
+| Embedding errors | Check `~/.unipi/memory/config.json` API key |

package/tools.ts

@@ -0,0 +1,131 @@
+/**
+ * tools.ts — CocoIndex tool registration
+ *
+ * Exposes cocoindex operations as Pi agent tools:
+ * - cocoindex_search: Search indexed content
+ * - cocoindex_status: Show indexing status
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { COCOINDEX_PACKAGE_SPEC, COCOINDEX_TOOLS } from "@pi-unipi/core";
+import * as bridge from "./bridge.js";
+import type { CocoindexDeps } from "./bridge.js";
+
+// ─────────────────────────────────────────────────────────
+// Schemas
+// ─────────────────────────────────────────────────────────
+
+const SearchParams = Type.Object({
+  query: Type.String({ description: "Search query against indexed content" }),
+  limit: Type.Optional(Type.Number({ description: "Max results (default 10)", minimum: 1 })),
+  offset: Type.Optional(Type.Number({ description: "Pagination offset", minimum: 0 })),
+});
+
+const StatusParams = Type.Object({});
+
+// ─────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────
+
+function textResult(text: string, details?: Record<string, unknown>): any {
+  return {
+    content: [{ type: "text", text }],
+    details,
+  };
+}
+
+function jsonResult(data: unknown, label?: string): any {
+  const text = label ? `${label}:\n${JSON.stringify(data, null, 2)}` : JSON.stringify(data, null, 2);
+  return {
+    content: [{ type: "text", text }],
+    details: data as Record<string, unknown>,
+  };
+}
+
+// ─────────────────────────────────────────────────────────
+// Registration
+// ─────────────────────────────────────────────────────────
+
+export function registerCocoindexTools(pi: ExtensionAPI, deps: CocoindexDeps): void {
+  // cocoindex_search — search indexed content via LanceDB
+  pi.registerTool({
+    name: COCOINDEX_TOOLS.SEARCH,
+    label: "CocoIndex Search",
+    description:
+      "Search indexed content using semantic vector search when available, with full-text/lexical fallbacks. " +
+      "Diagnostic/search only: this tool never installs CocoIndex. " +
+      "Use /unipi:cocoindex-init to set up/install, then /unipi:cocoindex-update to index.",
+    parameters: SearchParams,
+    async execute(_toolCallId: string, params: any): Promise<any> {
+      try {
+        const available = await bridge.isAvailable();
+        if (!available) {
+          return textResult(
+            "Search Unavailable: CocoIndex CLI is not installed. " +
+            "Run /unipi:cocoindex-init for guided install, or manually run " +
+            `uv tool install '${COCOINDEX_PACKAGE_SPEC}'.`,
+            { cliAvailable: false },
+          );
+        }
+
+        const results = await bridge.search(deps.projectDir, params.query, {
+          limit: params.limit,
+          offset: params.offset,
+        });
+
+        if (results.length === 0) {
+          return textResult(
+            `No results for "${params.query}" in the current CocoIndex data. ` +
+            "If this seems wrong, run /unipi:cocoindex-status to confirm the pipeline has data, then /unipi:cocoindex-update to refresh it.",
+          );
+        }
+
+        const lines = results.map(
+          (r, i) =>
+            `[${i + 1}] ${r.title} (${r.matchLayer}, rank: ${r.rank.toFixed(3)})\n${r.content.slice(0, 300)}`,
+        );
+        return textResult(
+          `Found ${results.length} results for "${params.query}":\n\n${lines.join("\n\n")}`,
+          { results } as unknown as Record<string, unknown>,
+        );
+      } catch (err) {
+        return textResult(`CocoIndex search error: ${err}`, { error: true });
+      }
+    },
+  } as any);
+
+  // cocoindex_status — show indexing status
+  pi.registerTool({
+    name: COCOINDEX_TOOLS.STATUS,
+    label: "CocoIndex Status",
+    description: "Check CocoIndex indexing status. Diagnostic only; use commands for interactive install/update.",
+    parameters: StatusParams,
+    async execute(): Promise<any> {
+      try {
+        const info = await bridge.status(deps.projectDir);
+        const lines = [
+          `📦 CocoIndex Status`,
+          `CLI available: ${info.cliAvailable ? "✅" : "❌"}`,
+          `Pipeline configured: ${info.pipelineConfigured ? "✅" : "❌"}`,
+          `Target store: ${info.targetStore}`,
+          `Indexed: ${info.indexed ? "✅" : "— (no data)"}`,
+          `Doc count: ${info.docCount}`,
+          `Last run: ${info.lastRun ?? "never"}`,
+        ];
+        if (!info.cliAvailable) {
+          lines.push(
+            "",
+            "Install guidance:",
+            "  • Run /unipi:cocoindex-init for guided install.",
+            `  • Manual: uv tool install '${COCOINDEX_PACKAGE_SPEC}'`,
+            "  • If uv is missing and mise is available: mise use -g uv@latest",
+          );
+        }
+        return textResult(lines.join("\n"), info as unknown as Record<string, unknown>);
+      } catch (err) {
+        return textResult(`CocoIndex status error: ${err}`, { error: true });
+      }
+    },
+  } as any);
+}