{"_id":"@cogitator-ai/rag","_rev":"6-dd17df1f8396b54086e4073fbd4cca73","name":"@cogitator-ai/rag","dist-tags":{"latest":"0.1.10"},"versions":{"0.1.0":{"name":"@cogitator-ai/rag","version":"0.1.0","license":"MIT","_id":"@cogitator-ai/rag@0.1.0","maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"dist":{"shasum":"6448e8c8b0919a6a7537b32abcf8f7ebedc3dbe7","tarball":"https://registry.npmjs.org/@cogitator-ai/rag/-/rag-0.1.0.tgz","fileCount":2,"integrity":"sha512-cuY7kcljJtbxYHtcldJnzFDne6o8uBG9QEFVxOC7FHVgKSem73+J8HOKiPPuiW7sX/lLu4QfIuKfcmt9VW7GhA==","signatures":[{"sig":"MEQCIHEAItA8iJjcCxVlgTlWfSfXTcH3VscOn7qHgeiqlBwNAiAweNcpqkA1CtEMnk6INU5eucxmSO8zxu26tHP9u4SRXQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11468},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"f512466d7a89483bc6d78661d66843f423488748","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"el1fe","email":"piuro.pavel@gmail.com"},"repository":{"url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","type":"git","directory":"packages/rag"},"_npmVersion":"10.9.0","description":"Retrieval Augmented Generation for Cogitator AI agents","directories":{},"_nodeVersion":"22.11.0","dependencies":{"zod":"^4.3.6","nanoid":"^5.0.4","@cogitator-ai/types":"workspace:*"},"publishConfig":{"access":"public","registry":"https://npm.pkg.github.com"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.7.2","@types/papaparse":"^5.3.15","@types/pdf-parse":"^1.1.5","@cogitator-ai/core":"workspace:*","@cogitator-ai/memory":"workspace:*"},"peerDependencies":{"@cogitator-ai/core":"workspace:*","@cogitator-ai/memory":"workspace:*"},"optionalDependencies":{"cheerio":"^1.0.0","papaparse":"^5.5.0","pdf-parse":"^1.1.1"},"peerDependenciesMeta":{"@cogitator-ai/core":{"optional":true},"@cogitator-ai/memory":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/rag_0.1.0_1771613029303_0.5122659235094769","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@cogitator-ai/rag","version":"0.1.3","license":"MIT","_id":"@cogitator-ai/rag@0.1.3","maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"dist":{"shasum":"06a0d9b06166ef4ebc0bf02e4b78eb5c41591971","tarball":"https://registry.npmjs.org/@cogitator-ai/rag/-/rag-0.1.3.tgz","fileCount":110,"integrity":"sha512-XjtVrztZjjxs/R02hl8h6tMz/CT281iRYTmySNVb4Y7vOP4WwApwCmnW/y0bbv/vIJkjSQm7U+qlmLcmCTasDA==","signatures":[{"sig":"MEUCIQCGilz5KhiZrusK1YP/K1PDxHYbnjjUJ2xq7RJoMnAwegIgJ3xh/vCuq+iXznPqCPpYoMqACMcVAeCAtU3LXKl/cvw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":141322},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"f508be4a1a30c7bd136f0fa8b2e6cee5521416ab","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"el1fe","email":"piuro.pavel@gmail.com"},"repository":{"url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","type":"git","directory":"packages/rag"},"_npmVersion":"10.9.0","description":"Retrieval Augmented Generation for Cogitator AI agents","directories":{},"_nodeVersion":"22.11.0","dependencies":{"zod":"^4.3.6","nanoid":"^5.0.4","@cogitator-ai/types":"workspace:*"},"publishConfig":{"access":"public","registry":"https://npm.pkg.github.com"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.7.2","@types/papaparse":"^5.3.15","@types/pdf-parse":"^1.1.5","@cogitator-ai/core":"workspace:*","@cogitator-ai/memory":"workspace:*"},"peerDependencies":{"@cogitator-ai/core":"workspace:*","@cogitator-ai/memory":"workspace:*"},"optionalDependencies":{"cheerio":"^1.0.0","papaparse":"^5.5.0","pdf-parse":"^1.1.1"},"peerDependenciesMeta":{"@cogitator-ai/core":{"optional":true},"@cogitator-ai/memory":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/rag_0.1.3_1772035715503_0.02004870710232365","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@cogitator-ai/rag","version":"0.1.4","license":"MIT","_id":"@cogitator-ai/rag@0.1.4","maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"dist":{"shasum":"fa86ed4e48c63046d0612e33887ae4dd386f7ca6","tarball":"https://registry.npmjs.org/@cogitator-ai/rag/-/rag-0.1.4.tgz","fileCount":110,"integrity":"sha512-wn1EYaXNlv6a1eLSoPJcv/Swtr7bqdRGs/EQnpYSuVIcTxHehiK42nyhD9M58AREDVohQl4crSVc7sm/3w3nnQ==","signatures":[{"sig":"MEUCIBlmVflFq8H+bDdE/Tk75GNFbztf8Sw/htbMQLzERcMjAiEAl0GHTpz/QSB3ZGcPbS8lwImcxvys9PNS2faGRSis+xQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":143923},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"467575702503c3581cb717f8aef8a72e1d8ae492","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"el1fe","email":"piuro.pavel@gmail.com"},"repository":{"url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","type":"git","directory":"packages/rag"},"_npmVersion":"10.9.0","description":"Retrieval Augmented Generation for Cogitator AI agents","directories":{},"_nodeVersion":"22.11.0","dependencies":{"zod":"^4.3.6","nanoid":"^5.0.4","@cogitator-ai/types":"workspace:*"},"publishConfig":{"access":"public","registry":"https://npm.pkg.github.com"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.7.2","@types/papaparse":"^5.3.15","@types/pdf-parse":"^1.1.5","@cogitator-ai/memory":"workspace:*"},"peerDependencies":{"@cogitator-ai/memory":"workspace:*"},"optionalDependencies":{"cheerio":"^1.0.0","papaparse":"^5.5.0","pdf-parse":"^1.1.1"},"peerDependenciesMeta":{"@cogitator-ai/memory":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/rag_0.1.4_1772049176725_0.5200365245248619","host":"s3://npm-registry-packages-npm-production"}},"0.1.8":{"name":"@cogitator-ai/rag","version":"0.1.8","license":"MIT","_id":"@cogitator-ai/rag@0.1.8","maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"dist":{"shasum":"b3d6ca24783e366f8d81131df8a46dd388d4c81e","tarball":"https://registry.npmjs.org/@cogitator-ai/rag/-/rag-0.1.8.tgz","fileCount":110,"integrity":"sha512-VXwt+CpenD8A/SiD3nbTljp3ECt5unCHS4+3iLueBSx1oIjYZAkKsarwnXoZ3mT99BXREIrRB3/Vjmq3RVqmKw==","signatures":[{"sig":"MEUCIBxUQFqvWDBsPn64leYPHIK/EKfL4VAXBy1GXuJZtjaQAiEA63e5yBThi/HUVkCIzxW36zHRKkBFb1mLlPhxNKYZXrw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":144211},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"33b6a8cb29bfdd7d2255acfa240b2df5d558354e","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"el1fe","email":"piuro.pavel@gmail.com"},"repository":{"url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","type":"git","directory":"packages/rag"},"_npmVersion":"10.9.0","description":"Retrieval Augmented Generation for Cogitator AI agents","directories":{},"_nodeVersion":"22.11.0","dependencies":{"zod":"^4.3.6","nanoid":"^5.0.4","@cogitator-ai/types":"workspace:*"},"publishConfig":{"access":"public","registry":"https://npm.pkg.github.com"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.7.2","@types/papaparse":"^5.3.15","@types/pdf-parse":"^1.1.5","@cogitator-ai/memory":"workspace:*"},"peerDependencies":{"@cogitator-ai/memory":"workspace:*"},"optionalDependencies":{"cheerio":"^1.0.0","papaparse":"^5.5.0","pdf-parse":"^1.1.1"},"peerDependenciesMeta":{"@cogitator-ai/memory":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/rag_0.1.8_1778881392881_0.8049035970704084","host":"s3://npm-registry-packages-npm-production"}},"0.1.9":{"name":"@cogitator-ai/rag","version":"0.1.9","license":"MIT","_id":"@cogitator-ai/rag@0.1.9","maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"dist":{"shasum":"201169dd83e5f5e9242b68d27a6f318f0f3c6a22","tarball":"https://registry.npmjs.org/@cogitator-ai/rag/-/rag-0.1.9.tgz","fileCount":111,"integrity":"sha512-9kArIJiWxg+/pGwFpsh5NBfm6nSyqUAZnN5IisxqdjKOOWfUw167bFXEpNx65lKE/H8J4UTldJnUhozISQRORg==","signatures":[{"sig":"MEUCIHVYruqy+cZLD0pErZqZOcCFlZswUoWkA9JUeF8dW6NvAiEAy0sK0+nV91xRn0vN2VBdinhfpCRAuHfU/Y1CZNMWbvM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":145274},"main":"./dist/index.js","type":"module","_from":"file:cogitator-ai-rag-0.1.9.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"el1fe","email":"piuro.pavel@gmail.com"},"_resolved":"/private/var/folders/20/4d95hdvj45j337gtqpbx3v1m0000gn/T/c9b2e517c31393b39ee8b1a9cee198e8/cogitator-ai-rag-0.1.9.tgz","_integrity":"sha512-9kArIJiWxg+/pGwFpsh5NBfm6nSyqUAZnN5IisxqdjKOOWfUw167bFXEpNx65lKE/H8J4UTldJnUhozISQRORg==","repository":{"url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","type":"git","directory":"packages/rag"},"_npmVersion":"10.9.0","description":"Retrieval Augmented Generation for Cogitator AI agents","directories":{},"_nodeVersion":"22.11.0","dependencies":{"zod":"^4.3.6","nanoid":"^5.0.4","@cogitator-ai/types":"0.22.2"},"publishConfig":{"access":"public","registry":"https://npm.pkg.github.com"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.7.2","@types/papaparse":"^5.3.15","@types/pdf-parse":"^1.1.5","@cogitator-ai/memory":"0.6.21"},"peerDependencies":{"@cogitator-ai/memory":"0.6.21"},"optionalDependencies":{"cheerio":"^1.0.0","papaparse":"^5.5.0","pdf-parse":"^1.1.1"},"peerDependenciesMeta":{"@cogitator-ai/memory":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/rag_0.1.9_1778882296429_0.7935144664454241","host":"s3://npm-registry-packages-npm-production"}},"0.1.10":{"name":"@cogitator-ai/rag","version":"0.1.10","description":"Retrieval Augmented Generation for Cogitator AI agents","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"dependencies":{"nanoid":"^5.0.4","zod":"^4.3.6","@cogitator-ai/types":"0.22.3"},"peerDependencies":{"@cogitator-ai/memory":"0.6.22"},"peerDependenciesMeta":{"@cogitator-ai/memory":{"optional":true}},"optionalDependencies":{"cheerio":"^1.0.0","papaparse":"^5.5.0","pdf-parse":"^1.1.1"},"devDependencies":{"@types/papaparse":"^5.3.15","@types/pdf-parse":"^1.1.5","typescript":"^5.7.2","vitest":"^4.0.18","@cogitator-ai/memory":"0.6.22"},"repository":{"type":"git","url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","directory":"packages/rag"},"publishConfig":{"access":"public","registry":"https://npm.pkg.github.com"},"license":"MIT","scripts":{"build":"tsc","dev":"tsc --watch","clean":"rm -rf dist","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest"},"_id":"@cogitator-ai/rag@0.1.10","bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","_integrity":"sha512-AchaU+HxyE1kiCAVXWoU+Jcj2OHB0q2df5M/hjGM+JyuTxRYKtTWeosysDdjOiHPtob75+LhiuA7NzHWm0tWnw==","_resolved":"/private/var/folders/20/4d95hdvj45j337gtqpbx3v1m0000gn/T/91797df0145fb95484055bab8831afa5/cogitator-ai-rag-0.1.10.tgz","_from":"file:cogitator-ai-rag-0.1.10.tgz","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-AchaU+HxyE1kiCAVXWoU+Jcj2OHB0q2df5M/hjGM+JyuTxRYKtTWeosysDdjOiHPtob75+LhiuA7NzHWm0tWnw==","shasum":"5684357957476cc38762afa4673d65754f64ae12","tarball":"https://registry.npmjs.org/@cogitator-ai/rag/-/rag-0.1.10.tgz","fileCount":111,"unpackedSize":161715,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDgRZ0vJ62D5hKFxp4J4ePdUx5wXEyrn9Hyc96oFft68QIhAOwOPOWs6ZkjUMHmx1l6S1k0QLPWLX2CbuvEZ80ZIGst"}]},"_npmUser":{"name":"el1fe","email":"piuro.pavel@gmail.com"},"directories":{},"maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/rag_0.1.10_1785059702939_0.4638520024129311"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-20T18:43:49.204Z","modified":"2026-07-26T09:55:03.249Z","0.1.0":"2026-02-20T18:43:49.428Z","0.1.3":"2026-02-25T16:08:35.708Z","0.1.4":"2026-02-25T19:52:56.895Z","0.1.8":"2026-05-15T21:43:13.019Z","0.1.9":"2026-05-15T21:58:16.621Z","0.1.10":"2026-07-26T09:55:03.078Z"},"bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"license":"MIT","homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","repository":{"type":"git","url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","directory":"packages/rag"},"description":"Retrieval Augmented Generation for Cogitator AI agents","maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"readme":"# @cogitator-ai/rag\n\nRetrieval-Augmented Generation pipeline for Cogitator AI agents. Load documents, chunk them, embed, retrieve, and rerank — all with a single builder API.\n\n## Installation\n\n```bash\npnpm add @cogitator-ai/rag\n\n# Optional dependencies for specific loaders\npnpm add cheerio    # HTML and web page loading\npnpm add papaparse  # CSV loading\npnpm add pdf-parse  # PDF loading\n```\n\n## Features\n\n- **7 Document Loaders** — Text, Markdown, JSON, CSV, HTML, PDF, Web pages\n- **3 Chunking Strategies** — Fixed-size, recursive, semantic (embedding-based)\n- **4 Retrieval Strategies** — Similarity, MMR, hybrid (BM25 + vector), multi-query\n- **2 Rerankers** — LLM-based scoring, Cohere Rerank API\n- **Pipeline Builder** — Fluent API to wire everything together\n- **Agent Tools** — Drop-in `rag_search` and `rag_ingest` tools for Cogitator agents\n- **Zod Validation** — Type-safe configuration with runtime checks\n\n---\n\n## Quick Start\n\n```typescript\nimport { RAGPipelineBuilder, TextLoader } from '@cogitator-ai/rag';\nimport { InMemoryEmbeddingAdapter, OpenAIEmbeddingService } from '@cogitator-ai/memory';\n\nconst pipeline = new RAGPipelineBuilder()\n  .withLoader(new TextLoader())\n  .withEmbeddingService(\n    new OpenAIEmbeddingService({\n      apiKey: process.env.OPENAI_API_KEY!,\n    })\n  )\n  .withEmbeddingAdapter(new InMemoryEmbeddingAdapter())\n  .withConfig({\n    chunking: { strategy: 'recursive', chunkSize: 500, chunkOverlap: 50 },\n    retrieval: { strategy: 'similarity', topK: 5, threshold: 0.3 },\n  })\n  .build();\n\n// ingest documents from a file or directory\nawait pipeline.ingest('./docs');\n\n// query the knowledge base\nconst results = await pipeline.query('How does authentication work?');\n\nfor (const r of results) {\n  console.log(`[${r.score.toFixed(3)}] ${r.content.slice(0, 100)}...`);\n}\n```\n\n---\n\n## Document Loaders\n\n| Loader           | Formats               | Optional Dep | Notes                         |\n| ---------------- | --------------------- | ------------ | ----------------------------- |\n| `TextLoader`     | `.txt`                | —            | Files and directories         |\n| `MarkdownLoader` | `.md`                 | —            | Strips frontmatter by default |\n| `JSONLoader`     | `.json`               | —            | Configurable content field    |\n| `CSVLoader`      | `.csv`                | `papaparse`  | Column selection, row mapping |\n| `HTMLLoader`     | `.html`, `.htm`       | `cheerio`    | CSS selector support          |\n| `PDFLoader`      | `.pdf`                | `pdf-parse`  | Text extraction from PDFs     |\n| `WebLoader`      | `http://`, `https://` | `cheerio`    | Fetches and parses web pages  |\n\n```typescript\nimport { MarkdownLoader, WebLoader, CSVLoader } from '@cogitator-ai/rag';\n\nconst md = new MarkdownLoader({ stripFrontmatter: true });\nconst web = new WebLoader({ selector: 'article' });\nconst csv = new CSVLoader({ contentColumn: 'body', metadataColumns: ['title'] });\n```\n\n---\n\n## Chunking Strategies\n\n| Strategy    | Class              | Best For                               |\n| ----------- | ------------------ | -------------------------------------- |\n| `fixed`     | `FixedSizeChunker` | Simple, predictable chunk sizes        |\n| `recursive` | `RecursiveChunker` | Respects paragraph/sentence boundaries |\n| `semantic`  | `SemanticChunker`  | Groups semantically similar sentences  |\n\n### Fixed-size\n\nSplits text into chunks of exactly `chunkSize` characters with optional overlap.\n\n```typescript\nimport { FixedSizeChunker } from '@cogitator-ai/rag';\n\nconst chunker = new FixedSizeChunker({ chunkSize: 500, chunkOverlap: 50 });\nconst chunks = chunker.chunk(text, documentId);\n```\n\n### Recursive\n\nSplits on configurable separators (`\\n\\n`, `\\n`, `. `, ` `) trying to keep paragraphs and sentences intact.\n\n```typescript\nimport { RecursiveChunker } from '@cogitator-ai/rag';\n\nconst chunker = new RecursiveChunker({\n  chunkSize: 500,\n  chunkOverlap: 50,\n  separators: ['\\n\\n', '\\n', '. ', ' '],\n});\n```\n\n### Semantic\n\nUses embedding similarity between sentences to find natural breakpoints. Async — requires an `EmbeddingService`.\n\n```typescript\nimport { SemanticChunker } from '@cogitator-ai/rag';\n\nconst chunker = new SemanticChunker({\n  embeddingService,\n  breakpointThreshold: 0.5,\n  minChunkSize: 100,\n  maxChunkSize: 2000,\n});\n\nconst chunks = await chunker.chunk(text, documentId);\n```\n\n### Factory\n\n```typescript\nimport { createChunker } from '@cogitator-ai/rag';\n\nconst chunker = createChunker(\n  { strategy: 'recursive', chunkSize: 500, chunkOverlap: 50 },\n  embeddingService\n);\n```\n\n---\n\n## Retrieval Strategies\n\n| Strategy      | Class                 | Description                                                   |\n| ------------- | --------------------- | ------------------------------------------------------------- |\n| `similarity`  | `SimilarityRetriever` | Pure cosine similarity search                                 |\n| `mmr`         | `MMRRetriever`        | Maximal Marginal Relevance — balances relevance and diversity |\n| `hybrid`      | `HybridRetriever`     | Combines BM25 keyword search with vector search (RRF)         |\n| `multi-query` | `MultiQueryRetriever` | Expands query into variants, merges results                   |\n\n### Similarity\n\n```typescript\nimport { SimilarityRetriever } from '@cogitator-ai/rag';\n\nconst retriever = new SimilarityRetriever({\n  embeddingAdapter,\n  embeddingService,\n  defaultTopK: 10,\n  defaultThreshold: 0.3,\n});\n\nconst results = await retriever.retrieve('What is TypeScript?');\n```\n\n### MMR\n\nReduces redundancy by penalizing results that are too similar to already-selected ones.\n\n```typescript\nimport { MMRRetriever } from '@cogitator-ai/rag';\n\nconst retriever = new MMRRetriever({\n  embeddingAdapter,\n  embeddingService,\n  defaultLambda: 0.7, // 1.0 = pure relevance, 0.0 = pure diversity\n  defaultTopK: 10,\n});\n```\n\n### Hybrid\n\nRequires `HybridSearch` from `@cogitator-ai/memory`.\n\n```typescript\nimport { HybridRetriever } from '@cogitator-ai/rag';\nimport { HybridSearch } from '@cogitator-ai/memory';\n\nconst retriever = new HybridRetriever({\n  hybridSearch,\n  defaultWeights: { bm25: 0.4, vector: 0.6 },\n});\n```\n\n### Multi-Query\n\nGenerates query variations and merges results. You provide the expansion function (typically an LLM call).\n\n```typescript\nimport { MultiQueryRetriever } from '@cogitator-ai/rag';\n\nconst retriever = new MultiQueryRetriever({\n  baseRetriever: similarityRetriever,\n  expandQuery: async (query) => {\n    const response = await llm.generate(\n      `Generate 3 alternative phrasings for: \"${query}\". Return one per line.`\n    );\n    return response.split('\\n').filter(Boolean);\n  },\n});\n```\n\n### Factory\n\n```typescript\nimport { createRetriever } from '@cogitator-ai/rag';\n\nconst retriever = createRetriever({\n  strategy: 'mmr',\n  embeddingAdapter,\n  embeddingService,\n  lambda: 0.7,\n  topK: 10,\n});\n```\n\n---\n\n## Reranking\n\nRerankers rescore retrieval results for higher precision. Enable via pipeline config.\n\n### LLM Reranker\n\nUses any LLM to score document relevance on a 0-10 scale.\n\n```typescript\nimport { LLMReranker } from '@cogitator-ai/rag';\n\nconst reranker = new LLMReranker({\n  generateFn: (prompt) => llm.generate(prompt),\n});\n\nconst pipeline = new RAGPipelineBuilder()\n  .withLoader(loader)\n  .withEmbeddingService(embeddingService)\n  .withEmbeddingAdapter(embeddingAdapter)\n  .withReranker(reranker)\n  .withConfig({\n    chunking: { strategy: 'recursive', chunkSize: 500, chunkOverlap: 50 },\n    retrieval: { strategy: 'similarity', topK: 20 },\n    reranking: { enabled: true, topN: 5 },\n  })\n  .build();\n```\n\n### Cohere Reranker\n\nUses the Cohere Rerank API (rerank-v3.5 by default).\n\n```typescript\nimport { CohereReranker } from '@cogitator-ai/rag';\n\nconst reranker = new CohereReranker({\n  apiKey: process.env.COHERE_API_KEY!,\n  model: 'rerank-v3.5',\n});\n```\n\n---\n\n## Agent Integration\n\nUse `ragTools()` to give a Cogitator agent access to your knowledge base.\n\n```typescript\nimport { Agent, tool } from '@cogitator-ai/core';\nimport { RAGPipelineBuilder, TextLoader, createSearchTool } from '@cogitator-ai/rag';\nimport { InMemoryEmbeddingAdapter, OpenAIEmbeddingService } from '@cogitator-ai/memory';\nimport { z } from 'zod';\n\nconst pipeline = new RAGPipelineBuilder()\n  .withLoader(new TextLoader())\n  .withEmbeddingService(new OpenAIEmbeddingService({ apiKey: process.env.OPENAI_API_KEY! }))\n  .withEmbeddingAdapter(new InMemoryEmbeddingAdapter())\n  .withConfig({\n    chunking: { strategy: 'recursive', chunkSize: 400, chunkOverlap: 50 },\n    retrieval: { strategy: 'similarity', topK: 3, threshold: 0.3 },\n  })\n  .build();\n\nawait pipeline.ingest('./knowledge-base');\n\nconst ragSearch = createSearchTool(pipeline);\n\nconst searchKB = tool({\n  name: ragSearch.name,\n  description: ragSearch.description,\n  parameters: z.object({\n    query: z.string().describe('Search query'),\n    limit: z.number().int().positive().optional(),\n    threshold: z.number().min(0).max(1).optional(),\n  }),\n  execute: async (params) => ragSearch.execute(params),\n});\n\nconst agent = new Agent({\n  name: 'docs-assistant',\n  model: 'gpt-4o',\n  instructions: 'Use rag_search to find information before answering.',\n  tools: [searchKB],\n});\n```\n\n---\n\n## Pipeline Stats\n\n```typescript\nconst stats = pipeline.getStats();\nconsole.log(stats.documentsIngested);\nconsole.log(stats.chunksStored);\nconsole.log(stats.queriesProcessed);\n```\n\n---\n\n## Examples\n\nSee [`examples/rag/`](../../examples/rag/) for runnable examples:\n\n- **01-basic-retrieval.ts** — Ingest documents and run semantic queries\n- **02-chunking-strategies.ts** — Compare fixed, recursive, and semantic chunking\n- **03-agent-with-rag.ts** — Full agent with RAG search tools\n\n---\n\n## Zod Schemas\n\n```typescript\nimport {\n  ChunkingStrategySchema,\n  ChunkingConfigSchema,\n  RetrievalStrategySchema,\n  RetrievalConfigSchema,\n  RerankingConfigSchema,\n  RAGPipelineConfigSchema,\n} from '@cogitator-ai/rag';\n```\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}