nx-semantic-matcher 1.0.0

package/README.md

@@ -0,0 +1,274 @@
+# nx-semantic-matcher
+
+**Tiered Text Matching Pipeline for TypeScript/Node.js**
+
+[![npm version](https://img.shields.io/npm/v/nx-semantic-matcher.svg)](https://www.npmjs.com/package/nx-semantic-matcher)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Match an input string against a list of candidate items using a 4-tier pipeline — each tier is progressively smarter and more expensive. The pipeline stops as soon as a confident match is found.
+
+| Tier | Name | Speed | Cost | What it handles |
+|------|------|-------|------|-----------------|
+| T1 | Exact / Normalized | ~0 ms | Free | Case, whitespace, punctuation differences |
+| T2 | Fuzzy (Fuse.js) | ~1–5 ms | Free | Typos, minor reordering, character transpositions |
+| T3 | Semantic Embeddings | ~10–80 ms | Free (local) / ~$0.02/M tokens (OpenAI) | Synonyms, paraphrasing, intent equivalence |
+| T4 | LLM Classification | ~500–3000 ms | Pay-per-call | Ambiguous edge cases — last resort |
+
+---
+
+## Install
+
+```bash
+npm install nx-semantic-matcher
+```
+
+Install optional providers for the tiers you need:
+
+```bash
+npm install @xenova/transformers    # Tier 3 – local embeddings (no API key, ~30 MB)
+npm install openai                  # Tier 3 OpenAI embeddings OR Tier 4 OpenAI LLM
+npm install @anthropic-ai/sdk       # Tier 4 Anthropic LLM
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { SemanticMatcher } from "nx-semantic-matcher";
+
+const questions = [
+  { id: "q1", text: "How do I reset my password?" },
+  { id: "q2", text: "What is your refund policy?" },
+  { id: "q3", text: "How do I contact support?" },
+];
+
+// Local embeddings — no API key needed, downloads ~30 MB on first run
+const matcher = new SemanticMatcher(questions, {
+  embedding: { provider: "local" },
+});
+
+const result = await matcher.match("Steps to change my password");
+
+if (result.found) {
+  console.log(`Matched: ${result.id} via Tier ${result.tier} (score ${result.score})`);
+  // → Matched: q1 via Tier 3 (score 0.87)
+} else {
+  console.log(`Not found: ${result.reason}`);
+}
+```
+
+---
+
+## Configuration
+
+```typescript
+import { SemanticMatcher, MatcherConfig } from "nx-semantic-matcher";
+
+const config: MatcherConfig = {
+  // Tier toggles and thresholds
+  tiers: {
+    t1: { enabled: true },
+    t2: { enabled: true, threshold: 0.72 },
+    t3: { enabled: true, threshold: 0.72, lazy: false },
+    t4: { enabled: false, threshold: "medium", maxCandidatesInPrompt: 100, timeout: 10000 },
+  },
+
+  // Embedding provider for T3
+  embedding: {
+    provider: "local",  // "local" | "openai" | EmbeddingProvider
+    // model: "Xenova/all-MiniLM-L6-v2",
+    // apiKey: "sk-...",
+  },
+
+  // LLM provider for T4 (only needed when t4.enabled is true)
+  llm: {
+    provider: "anthropic",  // "anthropic" | "openai" | LLMProvider
+    // model: "claude-3-5-haiku-20241022",
+    // apiKey: "...",
+  },
+
+  debug: false, // log tier decisions to stderr
+};
+```
+
+### Configuration Quick Reference
+
+| Config key | Default | Description |
+|---|---|---|
+| `tiers.t1.enabled` | `true` | Enable Tier 1 exact/normalized matching |
+| `tiers.t2.enabled` | `true` | Enable Tier 2 Fuse.js fuzzy matching |
+| `tiers.t2.threshold` | `0.72` | Min confidence for T2 match (0–1) |
+| `tiers.t3.enabled` | `true` | Enable Tier 3 embedding similarity |
+| `tiers.t3.threshold` | `0.72` | Min cosine similarity for T3 match |
+| `tiers.t3.lazy` | `false` | Defer index build to first query |
+| `tiers.t4.enabled` | `false` | Enable Tier 4 LLM classification |
+| `tiers.t4.threshold` | `"medium"` | Min LLM confidence: `"high"` or `"medium"` |
+| `tiers.t4.maxCandidatesInPrompt` | `100` | Max items sent to LLM |
+| `tiers.t4.timeout` | `10000` | LLM timeout in ms |
+| `embedding.provider` | — | `"local"` \| `"openai"` \| `EmbeddingProvider` |
+| `llm.provider` | — | `"anthropic"` \| `"openai"` \| `LLMProvider` |
+| `debug` | `false` | Log tier decisions to stderr |
+
+---
+
+## API
+
+### `new SemanticMatcher(items, config?)`
+
+Creates a new matcher. Builds the T3 embedding index eagerly unless `tiers.t3.lazy = true`.
+
+```typescript
+const matcher = new SemanticMatcher(
+  [{ id: "1", text: "..." }],
+  { embedding: { provider: "local" } }
+);
+```
+
+### `matcher.match(query)`
+
+Matches a query against the current item list.
+
+```typescript
+const result = await matcher.match("my query");
+// result: MatchFound | MatchNotFound
+```
+
+### `matcher.setItems(items)`
+
+Replaces the candidate list and rebuilds the embedding index.
+
+### `matcher.rebuildIndex()`
+
+Force-rebuilds the T3 index (e.g. after external mutation).
+
+### `matcher.dispose()`
+
+Releases model handles and clears in-memory vectors.
+
+### `SemanticMatcher.matchOnce(query, items, config?)`
+
+Static convenience method — creates, matches, and disposes in one call. Avoid in hot loops.
+
+---
+
+## Usage Examples
+
+### Fuzzy-only (no AI dependencies)
+
+```typescript
+const matcher = new SemanticMatcher(items, {
+  tiers: {
+    t3: { enabled: false },
+    t4: { enabled: false },
+  },
+});
+// T1 + T2 only — zero model downloads, synchronous-equivalent
+```
+
+### With LLM fallback (OpenAI)
+
+```typescript
+const matcher = new SemanticMatcher(items, {
+  embedding: { provider: "openai", apiKey: process.env.OPENAI_API_KEY },
+  tiers: {
+    t4: {
+      enabled: true,
+      provider: "openai",
+      threshold: "high",
+    },
+  },
+});
+```
+
+### Custom embedding provider
+
+```typescript
+import type { EmbeddingProvider } from "nx-semantic-matcher";
+
+class MyProvider implements EmbeddingProvider {
+  async embed(text: string): Promise<Float32Array> { /* ... */ }
+  async embedBatch(texts: string[]): Promise<Float32Array[]> { /* ... */ }
+}
+
+const matcher = new SemanticMatcher(items, {
+  tiers: { t3: { provider: new MyProvider() } },
+});
+```
+
+---
+
+## Provider Interfaces
+
+### `EmbeddingProvider`
+
+```typescript
+interface EmbeddingProvider {
+  embed(text: string): Promise<Float32Array>;
+  embedBatch?(texts: string[]): Promise<Float32Array[]>;
+  init?(): Promise<void>;
+  dispose?(): Promise<void>;
+}
+```
+
+### `LLMProvider`
+
+```typescript
+interface LLMProvider {
+  classify(query: string, candidates: MatchItem[]): Promise<LLMClassification>;
+}
+```
+
+---
+
+## Result Types
+
+```typescript
+type MatchResult = MatchFound | MatchNotFound;
+
+interface MatchFound {
+  found: true;
+  id: string;           // matched item id
+  text: string;         // matched item text
+  score: number;        // confidence [0, 1]
+  tier: 1 | 2 | 3 | 4; // which tier matched
+  tierName: string;     // human-readable tier label
+  durationMs: number;   // total pipeline duration
+  reasoning?: string;   // populated only for tier 4
+}
+
+interface MatchNotFound {
+  found: false;
+  durationMs: number;
+  reason: string;
+}
+```
+
+---
+
+## Error Handling
+
+`nx-semantic-matcher` **never throws for a failed match** — it returns `MatchNotFound`. It **does throw** for misconfiguration:
+
+| Error | Thrown when |
+|---|---|
+| `NxConfigError` | Invalid config at construction time |
+| `NxProviderError` | Provider init fails (bad API key, missing package) |
+| `NxIndexError` | Embedding index build or query fails |
+
+Tier 4 LLM errors (timeout, API 5xx, JSON parse failure) are caught silently — they log a warning (if `debug: true`) and the pipeline returns `NOT_FOUND`.
+
+---
+
+## Performance
+
+- **T1 + T2**: `< 5 ms` for up to 100,000 items.
+- **T3 index build**: ~50 ms per 1,000 items with the local model — run eagerly at startup.
+- **T3 query**: O(n·d) cosine scan. For n=10,000, d=384: ~15 ms on a modern CPU.
+- For n > 50,000 or sub-10 ms T3 requirements: plug in a vector database (pgvector, Qdrant) via a custom `EmbeddingProvider`.
+
+---
+
+## License
+
+MIT