claude-local-docs 1.0.13 → 1.0.15

package/dist/tei-client.js

@@ -0,0 +1,153 @@
+/**
+ * Shared TEI (Text Embeddings Inference) HTTP client with retry, timeout, and batching.
+ * Centralizes all TEI communication so embed, rerank, and code-embed share
+ * consistent error handling and diagnostics.
+ */
+const RETRYABLE_STATUSES = new Set([502, 503, 504]);
+export class TeiClient {
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    retryDelayMs;
+    maxBatchSize;
+    constructor(options) {
+        this.baseUrl = options.baseUrl;
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.retryDelayMs = options.retryDelayMs ?? 500;
+        this.maxBatchSize = options.maxBatchSize ?? 32;
+    }
+    /**
+     * Embed texts, automatically splitting into batches.
+     * Returns one embedding vector per input text.
+     */
+    async embed(inputs, options) {
+        const embeddings = [];
+        for (let i = 0; i < inputs.length; i += this.maxBatchSize) {
+            const batch = inputs.slice(i, i + this.maxBatchSize);
+            const body = { inputs: batch };
+            if (options?.truncate !== undefined)
+                body.truncate = options.truncate;
+            const data = await this.fetchWithRetry(`${this.baseUrl}/embed`, body);
+            embeddings.push(...data);
+        }
+        return embeddings;
+    }
+    /**
+     * Rerank texts against a query, automatically splitting into batches.
+     * Returns scored results sorted by score descending.
+     */
+    async rerank(query, texts) {
+        const allResults = [];
+        for (let i = 0; i < texts.length; i += this.maxBatchSize) {
+            const batch = texts.slice(i, i + this.maxBatchSize);
+            const data = await this.fetchWithRetry(`${this.baseUrl}/rerank`, {
+                query,
+                texts: batch,
+            });
+            const results = data;
+            // Offset indices back to original positions
+            for (const r of results) {
+                allResults.push({ index: r.index + i, score: r.score });
+            }
+        }
+        return allResults.sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Check if the TEI endpoint is healthy.
+     */
+    async checkHealth() {
+        try {
+            const res = await fetch(`${this.baseUrl}/health`, {
+                signal: AbortSignal.timeout(5_000),
+            });
+            if (res.ok)
+                return { healthy: true };
+            return { healthy: false, error: `HTTP ${res.status}` };
+        }
+        catch (err) {
+            return { healthy: false, error: err.message ?? String(err) };
+        }
+    }
+    async fetchWithRetry(url, body) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const res = await fetch(url, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+                if (res.ok) {
+                    return await res.json();
+                }
+                // Non-retryable HTTP error — fail immediately
+                if (!RETRYABLE_STATUSES.has(res.status)) {
+                    const text = await res.text();
+                    throw new Error(`TEI error: ${res.status} ${text}`);
+                }
+                // Retryable status — store error and retry
+                lastError = new Error(`TEI error: ${res.status}`);
+            }
+            catch (err) {
+                // Retryable network errors (ECONNREFUSED, timeout, etc.)
+                const isRetryable = err.name === "TimeoutError" ||
+                    err.cause?.code === "ECONNREFUSED" ||
+                    err.cause?.code === "ECONNRESET" ||
+                    RETRYABLE_STATUSES.has(err.status);
+                if (!isRetryable || attempt === this.maxRetries) {
+                    throw err;
+                }
+                lastError = err;
+            }
+            // Exponential backoff: 500ms, 1000ms
+            if (attempt < this.maxRetries) {
+                await new Promise((r) => setTimeout(r, this.retryDelayMs * (attempt + 1)));
+            }
+        }
+        throw lastError ?? new Error("TEI request failed after retries");
+    }
+}
+// --- Pre-configured singletons ---
+export const docEmbedClient = new TeiClient({
+    baseUrl: process.env.TEI_EMBED_URL ?? "http://localhost:39281",
+    maxBatchSize: 32,
+});
+export const rerankClient = new TeiClient({
+    baseUrl: process.env.TEI_RERANK_URL ?? "http://localhost:39282",
+    maxBatchSize: 32,
+});
+export const codeEmbedClient = new TeiClient({
+    baseUrl: process.env.TEI_CODE_EMBED_URL ?? "http://localhost:39283",
+    maxBatchSize: 8, // must match --max-client-batch-size 8 in docker-compose.yml / start-tei.sh
+});
+/**
+ * Truncate vectors to `dim` dimensions and L2-normalize.
+ * Shared by doc embeddings (Matryoshka 384-dim) and code embeddings (1536-dim).
+ */
+export function truncateAndNormalize(vectors, dim) {
+    return vectors.map(vec => {
+        const truncated = vec.slice(0, dim);
+        const norm = Math.sqrt(truncated.reduce((s, v) => s + v * v, 0));
+        return truncated.map(v => v / (norm || 1));
+    });
+}
+/**
+ * Check health of all 3 TEI endpoints.
+ * Returns per-endpoint status and an overall allHealthy flag.
+ */
+export async function checkAllTeiHealth() {
+    const [embed, rerank, codeEmbed] = await Promise.all([
+        docEmbedClient.checkHealth(),
+        rerankClient.checkHealth(),
+        codeEmbedClient.checkHealth(),
+    ]);
+    return {
+        allHealthy: embed.healthy && rerank.healthy && codeEmbed.healthy,
+        embed,
+        rerank,
+        codeEmbed,
+    };
+}
+//# sourceMappingURL=tei-client.js.map

package/dist/tei-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tei-client.js","sourceRoot":"","sources":["../src/tei-client.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -33,3 +33,52 @@ export interface DocRow {
     text: string;
     vector: number[];
 }
+export type CodeEntityType = "function" | "class" | "method" | "interface" | "type_alias" | "enum" | "import" | "variable" | "module" | "namespace" | "other";
+/** Shape of a code chunk row stored in LanceDB "code" table */
+export interface CodeRow {
+    id: number;
+    filePath: string;
+    language: string;
+    entityType: CodeEntityType;
+    entityName: string;
+    signature: string;
+    scopeChain: string;
+    lineStart: number;
+    lineEnd: number;
+    jsdoc: string;
+    decorators: string;
+    isExported: boolean;
+    isAsync: boolean;
+    isAbstract: boolean;
+    text: string;
+    vector: number[];
+}
+export interface CodeSearchResult {
+    score: number;
+    filePath: string;
+    language: string;
+    entityType: CodeEntityType;
+    entityName: string;
+    signature: string;
+    scopeChain: string[];
+    lineStart: number;
+    lineEnd: number;
+    content: string;
+    chunkId: number;
+}
+export interface IndexedFileMetadata {
+    filePath: string;
+    sha256: string;
+    language: string;
+    chunkCount: number;
+    indexedAt: string;
+}
+export interface CodeMetadata {
+    projectRoot: string;
+    files: IndexedFileMetadata[];
+    lastFullIndexAt?: string;
+    schemaVersion?: number;
+    lastIndexedCommit?: string;
+}
+/** Escape a string for use in LanceDB SQL filter expressions. */
+export declare function sqlEscapeString(value: string): string;

package/dist/types.js

@@ -1,2 +1,5 @@
-export {};
+/** Escape a string for use in LanceDB SQL filter expressions. */
+export function sqlEscapeString(value) {
+    return value.replace(/'/g, "''");
+}
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAiGA,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/unit.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Unit tests — no TEI containers needed.
+ * Tests: RRF fusion, file-walker, code-indexer AST chunking, markdown chunking,
+ *        SFC extraction, JSDoc/decorator/flags, TeiClient, git changes, utilities.
+ *
+ * Run: npm run test:unit
+ */
+export {};