@reftrixmcp/ml 0.1.7

package/dist/search/hybrid.js

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2025-2026 Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Hybrid Search Service
+ *
+ * Combines vector search (pgvector cosine similarity) and full-text search
+ * (PostgreSQL tsvector/tsquery) using Reciprocal Rank Fusion (RRF).
+ *
+ * Default weights: 60% vector + 40% full-text
+ */
+import { mergeWithRRF, normalizeRRFScore } from "./rrf.js";
+const DEFAULT_CONFIG = {
+    vectorWeight: 0.6,
+    fulltextWeight: 0.4,
+    k: 60,
+};
+/**
+ * Execute hybrid search by combining vector and full-text search results with RRF
+ *
+ * Both search functions are executed in parallel via Promise.all for minimum latency.
+ * Results are merged using Reciprocal Rank Fusion (RRF) with configurable weights.
+ *
+ * @param vectorSearchFn - Function that returns vector search results (ranked by cosine similarity)
+ * @param fulltextSearchFn - Function that returns full-text search results (ranked by ts_rank_cd)
+ * @param config - Optional hybrid search configuration
+ * @returns Merged results sorted by normalized RRF similarity score
+ */
+export async function executeHybridSearch(vectorSearchFn, fulltextSearchFn, config) {
+    const { vectorWeight, fulltextWeight, k } = {
+        ...DEFAULT_CONFIG,
+        ...config,
+    };
+    // Execute both searches in parallel for minimum latency
+    const [vectorResults, fulltextResults] = await Promise.all([
+        vectorSearchFn(),
+        fulltextSearchFn(),
+    ]);
+    // If one source returns empty, fall back to the other source only
+    if (vectorResults.length === 0 && fulltextResults.length === 0) {
+        return [];
+    }
+    // Merge with RRF
+    const merged = mergeWithRRF(vectorResults, fulltextResults, vectorWeight, fulltextWeight, k);
+    // Normalize scores and format output
+    return merged.map((item) => {
+        const source = {};
+        if (item.vectorRank !== undefined) {
+            source.vectorRank = item.vectorRank;
+        }
+        if (item.fulltextRank !== undefined) {
+            source.fulltextRank = item.fulltextRank;
+        }
+        return {
+            id: item.id,
+            similarity: normalizeRRFScore(item.rrfScore),
+            source,
+            data: item.data,
+        };
+    });
+}
+//# sourceMappingURL=hybrid.js.map

package/dist/search/hybrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid.js","sourceRoot":"","sources":["../../src/search/hybrid.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,yCAAyC;AAEzC;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AA+B3D,MAAM,cAAc,GAAiC;IACnD,YAAY,EAAE,GAAG;IACjB,cAAc,EAAE,GAAG;IACnB,CAAC,EAAE,EAAE;CACN,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,cAA2C,EAC3C,gBAA6C,EAC7C,MAA2B;IAE3B,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC,EAAE,GAAG;QAC1C,GAAG,cAAc;QACjB,GAAG,MAAM;KACV,CAAC;IAEF,wDAAwD;IACxD,MAAM,CAAC,aAAa,EAAE,eAAe,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACzD,cAAc,EAAE;QAChB,gBAAgB,EAAE;KACnB,CAAC,CAAC;IAEH,kEAAkE;IAClE,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/D,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,iBAAiB;IACjB,MAAM,MAAM,GAAoB,YAAY,CAC1C,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,CAAC,CACF,CAAC;IAEF,qCAAqC;IACrC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,IAAmB,EAAsB,EAAE;QAC5D,MAAM,MAAM,GAAiC,EAAE,CAAC;QAChD,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACtC,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QAC1C,CAAC;QACD,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,UAAU,EAAE,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC;YAC5C,MAAM;YACN,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/search/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Search utilities exports
+ *
+ * RRF utilities and types for WebDesign search services.
+ */
+export { calculateRRF, mergeWithRRF, normalizeRRFScore, toRankedItems } from "./rrf.js";
+export type { RankedItem, RRFScoredItem } from "./rrf.js";
+export { executeHybridSearch } from "./hybrid.js";
+export { buildFulltextConditions, buildFulltextRankExpression } from "./fulltext-helpers.js";
+export type { HybridSearchConfig, HybridSearchResult } from "./hybrid.js";
+export type { SearchFilters, SearchOptions, HybridSearchOptions, SearchResult, SummarySearchResult, SearchResultItem, SummarySearchResultItem, VectorSearchRawResult, FullTextSearchRawResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/search/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/search/index.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACxF,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAC7F,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC1E,YAAY,EACV,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/search/index.js

@@ -0,0 +1,11 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Search utilities exports
+ *
+ * RRF utilities and types for WebDesign search services.
+ */
+export { calculateRRF, mergeWithRRF, normalizeRRFScore, toRankedItems } from "./rrf.js";
+export { executeHybridSearch } from "./hybrid.js";
+export { buildFulltextConditions, buildFulltextRankExpression } from "./fulltext-helpers.js";
+//# sourceMappingURL=index.js.map

package/dist/search/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/search/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,yCAAyC;AAEzC;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAExF,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/search/rrf.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Reciprocal Rank Fusion (RRF) implementation
+ *
+ * RRF is a method for combining rankings from multiple search sources.
+ * It's particularly useful for hybrid search combining vector and full-text results.
+ *
+ * Formula: score = 1 / (k + rank)
+ * where k is a constant (typically 60) that prevents high-ranked items from
+ * dominating the final ranking.
+ */
+/**
+ * Item with ranking information from a single source
+ */
+export interface RankedItem {
+    id: string;
+    rank: number;
+    [key: string]: unknown;
+}
+/**
+ * Item with combined RRF score
+ */
+export interface RRFScoredItem {
+    id: string;
+    rrfScore: number;
+    vectorRank?: number;
+    fulltextRank?: number;
+    data: Record<string, unknown>;
+}
+/**
+ * Calculate RRF score for a single rank position
+ *
+ * @param rank - Rank position (1-based)
+ * @param k - Ranking constant (default 60)
+ * @returns RRF score
+ */
+export declare function calculateRRF(rank: number, k?: number): number;
+/**
+ * Merge results from vector and full-text search using RRF
+ *
+ * @param vectorResults - Results from vector similarity search
+ * @param fulltextResults - Results from full-text search
+ * @param vectorWeight - Weight for vector search results (default 0.6)
+ * @param fulltextWeight - Weight for full-text search results (default 0.4)
+ * @param k - RRF constant (default 60)
+ * @returns Merged and sorted results
+ */
+export declare function mergeWithRRF(vectorResults: RankedItem[], fulltextResults: RankedItem[], vectorWeight?: number, fulltextWeight?: number, k?: number): RRFScoredItem[];
+/**
+ * Convert an array of rows (with an `id` field) into RankedItem[] with 1-based ranks.
+ *
+ * The array order is preserved and used for rank assignment.
+ * All fields from each row are spread into the resulting RankedItem.
+ *
+ * @param rows - Array of objects that each contain at least an `id: string` field
+ * @returns RankedItem[] with rank starting from 1
+ */
+export declare function toRankedItems<T extends {
+    id: string;
+}>(rows: T[]): RankedItem[];
+/**
+ * Calculate effective score from RRF for display purposes
+ * Normalizes the RRF score to a 0-1 range
+ *
+ * @param rrfScore - Raw RRF score
+ * @param maxPossibleScore - Maximum possible score (sum of max vector and fulltext scores)
+ * @returns Normalized similarity score (0-1)
+ */
+export declare function normalizeRRFScore(rrfScore: number, maxPossibleScore?: number): number;
+//# sourceMappingURL=rrf.d.ts.map

package/dist/search/rrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrf.d.ts","sourceRoot":"","sources":["../../src/search/rrf.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,GAAE,MAAW,GAAG,MAAM,CAEjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,UAAU,EAAE,EAC3B,eAAe,EAAE,UAAU,EAAE,EAC7B,YAAY,GAAE,MAAY,EAC1B,cAAc,GAAE,MAAY,EAC5B,CAAC,GAAE,MAAW,GACb,aAAa,EAAE,CA4DjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,UAAU,EAAE,CAK/E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAMrF"}

package/dist/search/rrf.js

@@ -0,0 +1,108 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Calculate RRF score for a single rank position
+ *
+ * @param rank - Rank position (1-based)
+ * @param k - Ranking constant (default 60)
+ * @returns RRF score
+ */
+export function calculateRRF(rank, k = 60) {
+    return 1 / (k + rank);
+}
+/**
+ * Merge results from vector and full-text search using RRF
+ *
+ * @param vectorResults - Results from vector similarity search
+ * @param fulltextResults - Results from full-text search
+ * @param vectorWeight - Weight for vector search results (default 0.6)
+ * @param fulltextWeight - Weight for full-text search results (default 0.4)
+ * @param k - RRF constant (default 60)
+ * @returns Merged and sorted results
+ */
+export function mergeWithRRF(vectorResults, fulltextResults, vectorWeight = 0.6, fulltextWeight = 0.4, k = 60) {
+    const scoreMap = new Map();
+    // Process vector search results
+    vectorResults.forEach((item, index) => {
+        const rank = index + 1; // 1-based rank
+        const rrfScore = calculateRRF(rank, k) * vectorWeight;
+        const existing = scoreMap.get(item.id);
+        if (existing) {
+            existing.rrfScore += rrfScore;
+            existing.vectorRank = rank;
+        }
+        else {
+            const { id: _id, rank: _, ...data } = item;
+            scoreMap.set(item.id, {
+                id: item.id,
+                rrfScore,
+                vectorRank: rank,
+                data: data,
+            });
+        }
+    });
+    // Process full-text search results
+    fulltextResults.forEach((item, index) => {
+        const rank = index + 1; // 1-based rank
+        const rrfScore = calculateRRF(rank, k) * fulltextWeight;
+        const existing = scoreMap.get(item.id);
+        if (existing) {
+            existing.rrfScore += rrfScore;
+            existing.fulltextRank = rank;
+            // Merge additional data if not present
+            existing.data = { ...item, ...existing.data };
+        }
+        else {
+            const { id: _id, rank: _, ...data } = item;
+            scoreMap.set(item.id, {
+                id: item.id,
+                rrfScore,
+                fulltextRank: rank,
+                data: data,
+            });
+        }
+    });
+    // Convert to array and sort by RRF score (descending)
+    const merged = Array.from(scoreMap.values());
+    merged.sort((a, b) => b.rrfScore - a.rrfScore);
+    if (process.env.NODE_ENV === "development") {
+        // eslint-disable-next-line no-console
+        console.log("[Search] RRF merge completed:", {
+            vectorCount: vectorResults.length,
+            fulltextCount: fulltextResults.length,
+            mergedCount: merged.length,
+            topScore: merged[0]?.rrfScore,
+        });
+    }
+    return merged;
+}
+/**
+ * Convert an array of rows (with an `id` field) into RankedItem[] with 1-based ranks.
+ *
+ * The array order is preserved and used for rank assignment.
+ * All fields from each row are spread into the resulting RankedItem.
+ *
+ * @param rows - Array of objects that each contain at least an `id: string` field
+ * @returns RankedItem[] with rank starting from 1
+ */
+export function toRankedItems(rows) {
+    return rows.map((row, index) => ({
+        ...row,
+        rank: index + 1,
+    }));
+}
+/**
+ * Calculate effective score from RRF for display purposes
+ * Normalizes the RRF score to a 0-1 range
+ *
+ * @param rrfScore - Raw RRF score
+ * @param maxPossibleScore - Maximum possible score (sum of max vector and fulltext scores)
+ * @returns Normalized similarity score (0-1)
+ */
+export function normalizeRRFScore(rrfScore, maxPossibleScore) {
+    // Default max score: best possible rank (1) in both searches with default weights
+    const defaultMax = calculateRRF(1, 60) * 0.6 + calculateRRF(1, 60) * 0.4;
+    const maxScore = maxPossibleScore ?? defaultMax;
+    return Math.min(1, rrfScore / maxScore);
+}
+//# sourceMappingURL=rrf.js.map

package/dist/search/rrf.js.map

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

package/dist/search/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Search service type definitions
+ *
+ * WebDesign専用 - Layout (SectionPattern) and Motion (MotionPattern) search
+ */
+/**
+ * Search filter options for WebDesign patterns
+ */
+export interface SearchFilters {
+    /** Pattern type filter (hero, feature, cta, footer, etc.) */
+    type?: string | undefined;
+    /** Trigger filter for motion patterns (scroll, hover, click, load) */
+    trigger?: string | undefined;
+    /** Category filter for motion patterns (entrance, exit, emphasis, etc.) */
+    category?: string | undefined;
+    /** Tag filters */
+    tags?: string[] | undefined;
+    /** Page ID filter */
+    pageId?: string | undefined;
+}
+/**
+ * Search options for all search methods
+ */
+export interface SearchOptions {
+    /** Maximum number of results to return */
+    limit: number;
+    /** Offset for pagination */
+    offset?: number | undefined;
+    /** Search filters */
+    filters?: SearchFilters | undefined;
+    /** Summary mode: returns only id, name, similarity (default: false) */
+    summary?: boolean | undefined;
+}
+/**
+ * Hybrid search options extending base options
+ */
+export interface HybridSearchOptions extends SearchOptions {
+    /** Weight for vector search results (default 0.6) */
+    vectorWeight?: number | undefined;
+    /** Weight for full-text search results (default 0.4) */
+    fulltextWeight?: number | undefined;
+    /** Minimum similarity threshold (0-1) */
+    minSimilarity?: number | undefined;
+}
+/**
+ * Individual search result item for WebDesign patterns
+ */
+export interface SearchResultItem {
+    id: string;
+    name: string;
+    type: string;
+    description: string | undefined;
+    similarity: number;
+    /** HTML snippet for layout patterns */
+    htmlSnippet?: string | undefined;
+    /** Raw CSS for motion patterns */
+    rawCss?: string | undefined;
+    /** Trigger type for motion patterns */
+    trigger?: string | undefined;
+    /** Category for motion patterns */
+    category?: string | undefined;
+    /** Associated page ID */
+    pageId?: string | undefined;
+    createdAt: Date;
+}
+/**
+ * Summary search result item (lightweight, only essential fields)
+ */
+export interface SummarySearchResultItem {
+    id: string;
+    name: string;
+    similarity: number;
+}
+/**
+ * Search result with pagination info
+ */
+export interface SearchResult {
+    items: SearchResultItem[];
+    total: number;
+    limit: number;
+    offset: number;
+    searchTimeMs?: number;
+    /** Summary mode flag (only present when summary=true) */
+    _summary_mode?: true;
+}
+/**
+ * Summary search result with pagination info (lightweight response)
+ */
+export interface SummarySearchResult {
+    items: SummarySearchResultItem[];
+    total: number;
+    limit: number;
+    offset: number;
+    searchTimeMs?: number;
+    /** Summary mode flag (always true for summary results) */
+    _summary_mode: true;
+}
+/**
+ * Vector search raw result from database (section_patterns / motion_patterns)
+ */
+export interface VectorSearchRawResult {
+    id: string;
+    name: string;
+    type: string;
+    description?: string;
+    similarity: number;
+    html_snippet?: string;
+    raw_css?: string;
+    trigger?: string;
+    category?: string;
+    page_id?: string;
+    created_at: Date;
+}
+/**
+ * Full-text search raw result from database
+ */
+export interface FullTextSearchRawResult {
+    id: string;
+    name: string;
+    type: string;
+    description?: string;
+    rank: number;
+    html_snippet?: string;
+    raw_css?: string;
+    trigger?: string;
+    category?: string;
+    page_id?: string;
+    created_at: Date;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/search/types.d.ts.map

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

package/dist/search/types.js

@@ -0,0 +1,4 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=types.js.map

package/dist/search/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/search/types.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,yCAAyC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@reftrixmcp/ml",
+  "version": "0.1.7",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "description": "ML/Embedding services for Reftrix",
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./embeddings": {
+      "types": "./dist/embeddings/index.d.ts",
+      "default": "./dist/embeddings/index.js"
+    },
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "default": "./dist/search/index.js"
+    },
+    "./dinov2": {
+      "types": "./dist/dinov2/index.d.ts",
+      "default": "./dist/dinov2/index.js"
+    }
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "onnxruntime-node": "1.21.0",
+    "p-limit": "^3.1.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.0.14",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.14",
+    "@reftrixmcp/config": "0.1.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TKMD/ReftrixMCP.git",
+    "directory": "packages/ml"
+  },
+  "homepage": "https://github.com/TKMD/ReftrixMCP#readme",
+  "bugs": {
+    "url": "https://github.com/TKMD/ReftrixMCP/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "download:dinov2": "tsx scripts/download-dinov2.ts",
+    "clean": "rm -rf dist node_modules .turbo"
+  }
+}

package/src/dinov2/index.ts

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * DINOv2 visual embedding service exports
+ */
+
+export { DINOv2Service, DINOV2_EMBEDDING_DIMENSION, DINOV2_INPUT_SIZE } from "./service.js";
+export type { DINOv2ServiceConfig } from "./service.js";
+
+export type {
+  DINOv2WorkerInitMessage,
+  DINOv2WorkerInferMessage,
+  DINOv2WorkerDisposeMessage,
+  DINOv2WorkerMessage,
+  DINOv2WorkerInitResponse,
+  DINOv2WorkerInferResponse,
+  DINOv2WorkerDisposeResponse,
+  DINOv2WorkerErrorResponse,
+  DINOv2WorkerResponse,
+} from "./worker-thread-types.js";