diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..3081454
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+    groups:
+      pip-minor-patch:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      github-actions:
+        patterns:
+          - "*"
diff --git a/.github/issues/008-llm-generator.md b/.github/issues/008-llm-generator.md
index f5cd15b..81bf936 100644
--- a/.github/issues/008-llm-generator.md
+++ b/.github/issues/008-llm-generator.md
@@ -1,5 +1,5 @@
 ---
-title: "OpenAI / Anthropic LLM Generator"
+title: "OpenAI LLM Generator"
 labels: ["good first issue", "enhancement"]
 ---
 
diff --git a/.github/issues/011-inmemory-retriever-top-k-zero.md b/.github/issues/011-inmemory-retriever-top-k-zero.md
new file mode 100644
index 0000000..e1e6bf6
--- /dev/null
+++ b/.github/issues/011-inmemory-retriever-top-k-zero.md
@@ -0,0 +1,40 @@
+---
+title: "InMemoryRetriever returns every chunk when top_k <= 0"
+labels: ["bug", "good first issue"]
+---
+
+## Description
+
+`InMemoryRetriever.retrieve()` mishandles non-positive `top_k`. With 5 indexed chunks:
+
+```python
+r.retrieve(q, top_k=0)   # returns 5 chunks
+r.retrieve(q, top_k=-1)  # returns 4 chunks
+```
+
+Cause: `k = min(top_k, len(self._chunks))` gives `k = 0`, and `np.argpartition(scores, -0)[-0:]` is `[0:]` — the whole array. `FAISSRetriever` and `ChromaRetriever` both return `[]` for `top_k <= 0`, so the three built-in retrievers disagree.
+
+## Motivation
+
+Retrievers must behave identically for the same inputs so users can swap them freely. Returning the entire corpus for `top_k=0` can also silently blow up a prompt sent to an LLM generator.
+
+## Acceptance criteria
+
+- [ ] `InMemoryRetriever.retrieve()` returns `[]` when `top_k <= 0`
+- [ ] Non-integer / bool `top_k` raises `RetrieverError` (mirror `FAISSRetriever.retrieve`)
+- [ ] Regression tests in `tests/test_retriever/test_in_memory.py` for `top_k` in `(0, -1, True)`
+- [ ] `Retriever.retrieve` docstring in `ragframework/base.py` states the contract: non-positive `top_k` → empty list
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Fixed`
+
+## Files to touch
+
+- `ragframework/retriever/in_memory.py` — `retrieve()` (lines 38–48)
+- `ragframework/base.py` — `Retriever.retrieve` docstring
+- `tests/test_retriever/test_in_memory.py`
+
+## Resources
+
+- `FAISSRetriever.retrieve` in `ragframework/retriever/faiss.py` for the reference behaviour
+- `test_non_positive_top_k_returns_empty` in `tests/test_retriever/test_chroma.py`
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/012-loader-unicode-decode-error.md b/.github/issues/012-loader-unicode-decode-error.md
new file mode 100644
index 0000000..51e5be2
--- /dev/null
+++ b/.github/issues/012-loader-unicode-decode-error.md
@@ -0,0 +1,39 @@
+---
+title: "TextFileLoader / MarkdownLoader leak UnicodeDecodeError instead of LoaderError"
+labels: ["bug", "good first issue"]
+---
+
+## Description
+
+Both file loaders only catch `OSError` around `path.read_text(...)`. A file that is not valid in the configured encoding raises a raw `UnicodeDecodeError` (a `ValueError`), and an unknown encoding name raises `LookupError`:
+
+```python
+TextFileLoader().load("latin1.txt")            # UnicodeDecodeError
+TextFileLoader(encoding="nope").load("a.txt")  # LookupError
+```
+
+The documented contract (`ragframework/exceptions.py`, `CONTRIBUTING.md`) is that loaders raise `LoaderError`.
+
+## Motivation
+
+Callers that catch `LoaderError` (or `RAGFrameworkError`) miss these failures. The pipeline still wraps them in `PipelineError`, but direct loader users do not get the promised exception type.
+
+## Acceptance criteria
+
+- [ ] `UnicodeDecodeError` and `LookupError` are converted to `LoaderError` with the file path and encoding in the message
+- [ ] The duplicated exists / is_file / read_text block in `TextFileLoader` and `MarkdownLoader` is extracted into a private helper (e.g. `_read_text_file(path, encoding)`) so the fix lives in one place
+- [ ] Optional: `errors: str = "strict"` constructor argument passed through to `read_text` so users can opt into `"replace"`
+- [ ] Tests for both failure modes in `tests/test_document/test_loaders.py`
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Fixed`
+
+## Files to touch
+
+- `ragframework/document/loaders.py` — `TextFileLoader.load`, `MarkdownLoader.load`
+- `tests/test_document/test_loaders.py`
+
+## Resources
+
+- [`Path.read_text`](https://docs.python.org/3/library/pathlib.html#pathlib.Path.read_text)
+- [Error handlers](https://docs.python.org/3/library/codecs.html#error-handlers)
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/013-fixed-size-chunker-validation.md b/.github/issues/013-fixed-size-chunker-validation.md
new file mode 100644
index 0000000..08e4901
--- /dev/null
+++ b/.github/issues/013-fixed-size-chunker-validation.md
@@ -0,0 +1,42 @@
+---
+title: "FixedSizeChunker accepts chunk_size <= 0 and negative chunk_overlap"
+labels: ["bug", "good first issue"]
+---
+
+## Description
+
+`FixedSizeChunker.__init__` only checks `chunk_overlap >= chunk_size`. Invalid values slip through and produce garbage:
+
+```python
+FixedSizeChunker(chunk_size=0, chunk_overlap=-1).chunk(Document("d", "hello"))
+# -> 5 empty chunks
+
+FixedSizeChunker(chunk_size=10, chunk_overlap=-5).chunk(Document("d", "0123456789ABCDEFGHIJKLMNOPQRS"))
+# -> ['0123456789', 'FGHIJKLMNO']   characters A–E and P–S silently dropped
+```
+
+`RecursiveChunker` and `RAGConfig` already validate all three conditions; `FixedSizeChunker` and `SentenceChunker` do not.
+
+## Motivation
+
+Negative overlap silently loses text from the index — the worst kind of bug for a retrieval system, because nothing fails and recall just degrades.
+
+## Acceptance criteria
+
+- [ ] `FixedSizeChunker` raises `ValueError` for `chunk_size <= 0` or `chunk_overlap < 0` (same messages as `RecursiveChunker`)
+- [ ] `SentenceChunker` raises `ValueError` for `max_sentences <= 0` or `overlap_sentences < 0`
+- [ ] `RecursiveChunker.from_config(config)` added, matching the classmethod `FixedSizeChunker` already has
+- [ ] Parametrised tests in `tests/test_document/test_chunkers.py` covering each invalid value
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Fixed`
+
+## Files to touch
+
+- `ragframework/document/chunkers.py` — `FixedSizeChunker.__init__` (line 21), `SentenceChunker.__init__` (line 65)
+- `tests/test_document/test_chunkers.py`
+
+## Resources
+
+- `RecursiveChunker.__init__` (lines 116–121) for the validation to copy
+- `RAGConfig.__post_init__` in `ragframework/config.py`
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/014-inmemory-retriever-dimension-check.md b/.github/issues/014-inmemory-retriever-dimension-check.md
new file mode 100644
index 0000000..1c963fa
--- /dev/null
+++ b/.github/issues/014-inmemory-retriever-dimension-check.md
@@ -0,0 +1,43 @@
+---
+title: "InMemoryRetriever raises raw numpy ValueError on embedding dimension mismatch"
+labels: ["bug", "good first issue"]
+---
+
+## Description
+
+`InMemoryRetriever` performs no validation of vector shape or content:
+
+```python
+r.add([Chunk(id="a", content="a", embedding=[1.0, 0.0, 0.0])])
+r.add([Chunk(id="b", content="b", embedding=[1.0, 0.0])])   # ValueError from np.array (ragged)
+r.retrieve([1.0, 0.0])                                        # ValueError from matrix @ q
+```
+
+`FAISSRetriever` already has `_validated_vector()` that checks 1-D, non-empty, finite, non-zero, and enforces a consistent dimension across `add()` and `retrieve()`, raising `RetrieverError` with a clear message. `InMemoryRetriever` should behave the same way.
+
+## Motivation
+
+Dimension mismatches are the most common mistake when swapping embedders (e.g. 384-dim MiniLM vs 1536-dim OpenAI). Users deserve `RetrieverError: Query embedding has dimension 384; expected 1536.` rather than a numpy shape error.
+
+## Acceptance criteria
+
+- [ ] Move `FAISSRetriever._validated_vector` into a shared helper, e.g. `ragframework/utils/vectors.py::validate_vector(values, label) -> np.ndarray`
+- [ ] `InMemoryRetriever.add()` validates every chunk vector before mutating state and tracks `self._dimension`
+- [ ] `InMemoryRetriever.retrieve()` validates the query vector and its dimension, raising `RetrieverError`
+- [ ] `FAISSRetriever` uses the shared helper (behaviour unchanged, its tests still pass)
+- [ ] Tests in `tests/test_retriever/test_in_memory.py` for: wrong dimension on add, wrong dimension on query, NaN, zero vector, empty vector
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Fixed`
+
+## Files to touch
+
+- `ragframework/utils/vectors.py` — new
+- `ragframework/utils/__init__.py` — export
+- `ragframework/retriever/in_memory.py`
+- `ragframework/retriever/faiss.py` — replace private static method with the helper
+- `tests/test_retriever/test_in_memory.py`
+
+## Resources
+
+- `FAISSRetriever._validated_vector` (`ragframework/retriever/faiss.py` lines 131–144)
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/015-inmemory-retriever-incremental-add.md b/.github/issues/015-inmemory-retriever-incremental-add.md
new file mode 100644
index 0000000..6989206
--- /dev/null
+++ b/.github/issues/015-inmemory-retriever-incremental-add.md
@@ -0,0 +1,37 @@
+---
+title: "InMemoryRetriever.add() re-normalises the entire matrix on every call (O(N²))"
+labels: ["bug", "good first issue"]
+---
+
+## Description
+
+Every call to `InMemoryRetriever.add()` rebuilds `self._matrix` from **all** stored chunks:
+
+```python
+self._chunks.extend(chunks)
+vectors = np.array([c.embedding for c in self._chunks], dtype=np.float32)  # all N, every time
+```
+
+Ingesting N documents one at a time is therefore O(N²). Measured locally: 2 000 single-chunk `add()` calls with 64-dim vectors take ~2 s; 20 000 would take minutes.
+
+## Motivation
+
+`RAGPipeline.ingest()` is called once per source, so per-file ingestion of a folder hits exactly this path. Incremental ingestion should be linear.
+
+## Acceptance criteria
+
+- [ ] `add()` normalises only the **new** vectors and appends them (`np.vstack` onto the existing matrix, or keep a list of row blocks and concatenate lazily on first `retrieve()` after a change)
+- [ ] Retrieval results are identical before/after the change (existing tests pass)
+- [ ] A test that adds chunks in several batches and asserts `len(r)` and the top result match a single-batch add
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Fixed`
+
+## Files to touch
+
+- `ragframework/retriever/in_memory.py` — `add()` (lines 25–36)
+- `tests/test_retriever/test_in_memory.py`
+
+## Resources
+
+- [`numpy.vstack`](https://numpy.org/doc/stable/reference/generated/numpy.vstack.html)
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/016-idempotent-retriever-add.md b/.github/issues/016-idempotent-retriever-add.md
new file mode 100644
index 0000000..5f841c8
--- /dev/null
+++ b/.github/issues/016-idempotent-retriever-add.md
@@ -0,0 +1,42 @@
+---
+title: "Re-ingesting the same source duplicates chunks in InMemoryRetriever and FAISSRetriever"
+labels: ["bug", "help wanted"]
+---
+
+## Description
+
+`RAGPipeline.ingest(path)` called twice on the same file doubles the index:
+
+```python
+pipe.ingest("doc.txt")   # 12 chunks
+pipe.ingest("doc.txt")   # 12 chunks
+len(pipe.retriever)      # 24  — same 12 chunk ids stored twice
+```
+
+`ChromaRetriever.add()` uses `upsert`, so it is idempotent on chunk id. `InMemoryRetriever` and `FAISSRetriever` blindly append. The `Retriever.add` docstring in `base.py` does not say which behaviour is correct.
+
+## Motivation
+
+Re-running an ingestion script (the normal workflow while iterating) silently pollutes results: the same chunk appears multiple times in `top_k`, crowding out genuinely different context. Chunk ids are already deterministic (`<doc_id>:<index>`, where `doc_id` is a hash of the source path), so idempotency is achievable.
+
+## Acceptance criteria
+
+- [ ] `Retriever.add` docstring in `ragframework/base.py` defines the contract: adding a chunk whose `id` already exists **replaces** it (upsert semantics)
+- [ ] `InMemoryRetriever.add()` replaces existing rows by id (maintain an `id -> row index` dict)
+- [ ] `FAISSRetriever.add()` handles duplicates. `IndexHNSWFlat` does not support removal, so pick and document one approach: (a) keep an `id -> label` map and tombstone superseded labels (filtered out in `retrieve`, over-fetching to compensate), or (b) wrap the index in `faiss.IndexIDMap2` if it supports the chosen index type. Explain the trade-off in the docstring.
+- [ ] Tests for all three retrievers: add the same chunk twice → `len()` unchanged, retrieval returns it once, and the **new** content/embedding wins
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Fixed`
+
+## Files to touch
+
+- `ragframework/base.py` — `Retriever.add` docstring
+- `ragframework/retriever/in_memory.py`
+- `ragframework/retriever/faiss.py`
+- `tests/test_retriever/test_in_memory.py`, `tests/test_retriever/test_faiss.py`, `tests/test_retriever/test_chroma.py`
+
+## Resources
+
+- [FAISS: removing vectors](https://github.com/facebookresearch/faiss/wiki/Special-operations-on-indexes#removing-elements-from-an-index)
+- `ChromaRetriever.add` for the upsert reference behaviour
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/issues/017-ragconfig-not-applied.md b/.github/issues/017-ragconfig-not-applied.md
new file mode 100644
index 0000000..9544340
--- /dev/null
+++ b/.github/issues/017-ragconfig-not-applied.md
@@ -0,0 +1,48 @@
+---
+title: "RAGConfig.chunk_size / chunk_overlap / embedding_dim are silently ignored by RAGPipeline"
+labels: ["bug", "help wanted"]
+---
+
+## Description
+
+`RAGPipeline` reads exactly one field from its config — `top_k`. The other three are dead:
+
+```python
+pipe = RAGPipeline(
+    chunker=FixedSizeChunker(),            # chunk_size=512
+    embedder=RandomEmbedder(dim=16),
+    config=RAGConfig(chunk_size=20, chunk_overlap=5, embedding_dim=8),
+    ...
+)
+pipe.chunker.chunk_size   # 512 — config ignored, no warning
+pipe.embedder.dim         # 16  — embedding_dim=8 never checked
+```
+
+The `RAGConfig` docstring says `embedding_dim` "must match the Embedder in use", but nothing verifies it. Only `FixedSizeChunker.from_config()` consumes the chunk fields, and it must be called by hand.
+
+## Motivation
+
+Users reading the README's `config=RAGConfig(top_k=5)` example reasonably assume the other fields work the same way. A config object that looks authoritative but isn't is a trap.
+
+## Proposed resolution
+
+1. **Enforce `embedding_dim`.** In `ingest()` and `query()`, after the first `embed()` call, compare `len(vector)` to `config.embedding_dim` and raise `PipelineError("Embedder produced 16-dim vectors but RAGConfig.embedding_dim is 8")`. Change the default to `embedding_dim: int | None = None` so the check is opt-in and existing users are not broken.
+2. **Make the chunk fields usable.** Add `RAGPipeline.from_config(config, *, loader, embedder, retriever, generator, chunker_cls=FixedSizeChunker)` classmethod that builds the chunker via `chunker_cls.from_config(config)` (depends on `RecursiveChunker.from_config` from #25).
+3. **Document** in the `RAGConfig` docstring which fields the pipeline enforces vs. which are consumed only by `from_config` helpers.
+
+## Acceptance criteria
+
+- [ ] `embedding_dim` mismatch raises `PipelineError` with both numbers in the message; `None` disables the check
+- [ ] `RAGPipeline.from_config(...)` exists and is covered by a test
+- [ ] `RAGConfig` docstring updated; README Quick Start mentions `from_config`
+- [ ] Existing tests pass unchanged (default `RAGConfig()` must still work with `RandomEmbedder(dim=16)` in `tests/`) — hence the `None` default
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Fixed` / `### Changed`
+
+## Files to touch
+
+- `ragframework/config.py`
+- `ragframework/pipeline/rag.py`
+- `tests/test_pipeline/test_rag.py`, `tests/test_config.py`
+- `README.md`
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/issues/018-getting-started-markdown-broken.md b/.github/issues/018-getting-started-markdown-broken.md
new file mode 100644
index 0000000..a3c036e
--- /dev/null
+++ b/.github/issues/018-getting-started-markdown-broken.md
@@ -0,0 +1,39 @@
+---
+title: "docs/getting-started.md renders as plain text (escaped headings, HTML entities, 322 blank lines)"
+labels: ["bug", "documentation", "good first issue"]
+---
+
+## Description
+
+`docs/getting-started.md` appears to have been exported from a rich-text editor. On GitHub it renders as one unformatted blob:
+
+- Every heading is escaped: `\# Getting Started`, `\## Installation`, `\### Requirements` (29 occurrences)
+- Indentation inside code blocks is written as `&#x20;` HTML entities
+- Underscores are escaped: `chunk\_size`, `top\_k`
+- 322 of the 480 lines are blank (every paragraph is separated by 3 empty lines)
+- File uses CRLF line endings (see the `.gitattributes` issue)
+
+## Motivation
+
+This is the first document a new contributor or user opens after the README. Right now it is unreadable, which undermines the whole onboarding story.
+
+## Acceptance criteria
+
+- [ ] All `\#` headings converted to real Markdown headings with a sensible hierarchy (`#` → `##` → `###`)
+- [ ] `&#x20;` and `\_` escapes removed; code samples are inside fenced ` ```python ` blocks and actually run against the current API
+- [ ] Blank-line bloat collapsed to standard single blank lines between paragraphs
+- [ ] Content checked against the current codebase: mentions `PDFLoader`, `RecursiveChunker`, `HuggingFaceEmbedder`, `FAISSRetriever`, `ChromaRetriever` where relevant
+- [ ] File saved with LF line endings
+- [ ] Linked from `README.md` (it currently is not) and from `CONTRIBUTING.md`
+
+## Files to touch
+
+- `docs/getting-started.md`
+- `README.md` — add a link under Quick Start
+- `CONTRIBUTING.md` — add a link
+
+## Resources
+
+- `README.md` Quick Start and `examples/basic_rag.py` as the source of truth for working code
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/019-stale-roadmap-and-docs.md b/.github/issues/019-stale-roadmap-and-docs.md
new file mode 100644
index 0000000..ec29324
--- /dev/null
+++ b/.github/issues/019-stale-roadmap-and-docs.md
@@ -0,0 +1,32 @@
+---
+title: "README roadmap, GOOD_FIRST_ISSUES.md and CHANGELOG are out of date"
+labels: ["documentation", "good first issue"]
+---
+
+## Description
+
+Several docs still describe the v0.1.0 state:
+
+- **`README.md` Roadmap table** marks PDF loader, HuggingFace embedder, FAISS, ChromaDB, recursive chunker and Jupyter notebook as `Open` — all six are merged (issues #1, #3, #4, #5, #7, #10 closed)
+- **`.github/GOOD_FIRST_ISSUES.md`** says issues "will be opened" and lists the same six finished items as available work; it also duplicates the content of `.github/issues/*.md`, so it drifts every time an issue file changes
+- **`CHANGELOG.md`** `[Unreleased]` section: missing blank line before `## [0.1.0]`, and two entries lack backticks (`RecursiveChunker`, `PDFLoader`) unlike the others
+- **`examples/README.md`** says OpenAI integrations "are not included" — still true, but it should point at the open issues (#6, #8, #20) instead of the stale good-first-issues file
+- Ten source docstrings reference `.github/GOOD_FIRST_ISSUES.md` (e.g. `InMemoryRetriever`, `EchoGenerator`, `RandomEmbedder`, `loaders.py`, `chunkers.py`) — they should link to the GitHub issues page instead so they don't rot
+
+## Acceptance criteria
+
+- [ ] Roadmap table reflects reality (Done / Open / In progress) and links each row to its issue number
+- [ ] `GOOD_FIRST_ISSUES.md` becomes a short pointer: how to find issues (`label:"good first issue"` link), how to claim one, link to `CONTRIBUTING.md`. Detailed specs live only in `.github/issues/*.md` + GitHub
+- [ ] `CHANGELOG.md` formatting fixed
+- [ ] Docstring references updated to `https://github.com/adaumsilva/RAG-framework/issues`
+- [ ] `examples/README.md` links to the open integration issues
+
+## Files to touch
+
+- `README.md`
+- `.github/GOOD_FIRST_ISSUES.md`
+- `CHANGELOG.md`
+- `examples/README.md`
+- `ragframework/document/loaders.py`, `ragframework/document/chunkers.py`, `ragframework/embeddings/random_embedder.py`, `ragframework/retriever/in_memory.py`, `ragframework/generator/echo_generator.py`
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/020-sentence-chunker-max-chars.md b/.github/issues/020-sentence-chunker-max-chars.md
new file mode 100644
index 0000000..35879bd
--- /dev/null
+++ b/.github/issues/020-sentence-chunker-max-chars.md
@@ -0,0 +1,26 @@
+---
+title: "SentenceChunker: enforce a maximum character length per chunk"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+`SentenceChunker` groups N sentences per chunk with no upper bound on characters. A document with three 5 000-character "sentences" yields a single 15 005-character chunk, which will exceed most embedding models' context windows and get truncated silently by the provider.
+
+## Motivation
+
+Chunk size limits are the whole point of chunking. Every other chunker in the package is size-bounded; this one should be too.
+
+## Acceptance criteria
+
+- [ ] New constructor argument `max_chars: int | None = None`. When set, a window that would exceed `max_chars` is closed early (fewer than `max_sentences`), and a single sentence longer than `max_chars` is hard-split at `max_chars` (reuse the fixed-window logic from `FixedSizeChunker`, or delegate to `RecursiveChunker` with `separators=[" ", ""]`)
+- [ ] `max_chars <= 0` raises `ValueError`
+- [ ] Tests: window closes early; oversized single sentence is split; `None` preserves current behaviour
+- [ ] Docstring updated; `CHANGELOG.md` updated under `[Unreleased]` → `### Added`
+
+## Files to touch
+
+- `ragframework/document/chunkers.py` — `SentenceChunker`
+- `tests/test_document/test_chunkers.py`
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/021-retrieval-scores.md b/.github/issues/021-retrieval-scores.md
new file mode 100644
index 0000000..ff30d36
--- /dev/null
+++ b/.github/issues/021-retrieval-scores.md
@@ -0,0 +1,43 @@
+---
+title: "Expose similarity scores from retrievers and in RAGResponse"
+labels: ["enhancement", "help wanted"]
+---
+
+## Description
+
+All three retrievers compute a similarity score and throw it away:
+
+- `InMemoryRetriever.retrieve` — `scores = self._matrix @ q`, only used for ordering
+- `FAISSRetriever.retrieve` — `_scores, labels = self._index.search(...)`
+- `ChromaRetriever.retrieve` — `include=["documents", "metadatas"]` (omits `"distances"`)
+
+Users cannot filter by a relevance threshold, log retrieval quality, or show confidence in a UI.
+
+## Proposed design
+
+- Add `score: float | None = None` to the `Chunk` dataclass (last field, default `None`, so existing code is unaffected)
+- Each retriever sets `score` on the **returned** chunks. Returned chunks should be shallow copies (`dataclasses.replace(chunk, score=s)`) so the stored chunk is not mutated
+- Document the scale: cosine similarity in `[-1, 1]`, higher is better. `ChromaRetriever` must convert Chroma's distance — create collections with `metadata={"hnsw:space": "cosine"}` explicitly (Chroma defaults to L2) and return `1 - distance`
+- Add `RAGConfig.score_threshold: float | None = None`; `RAGPipeline.query()` drops chunks below it before generation
+
+## Acceptance criteria
+
+- [ ] `Chunk.score` field added and documented
+- [ ] All three retrievers populate it; tests assert the top result's score ≈ 1.0 for an identical vector and that the stored chunk's `score` stays `None`
+- [ ] `ChromaRetriever` creates collections with an explicit cosine space
+- [ ] `score_threshold` implemented in the pipeline with a test
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Added`
+
+## Files to touch
+
+- `ragframework/base.py` — `Chunk`
+- `ragframework/retriever/in_memory.py`, `faiss.py`, `chroma.py`
+- `ragframework/config.py`, `ragframework/pipeline/rag.py`
+- Tests for each
+
+## Resources
+
+- [Chroma distance functions](https://docs.trychroma.com/docs/collections/configure)
+- [`dataclasses.replace`](https://docs.python.org/3/library/dataclasses.html#dataclasses.replace)
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/issues/022-directory-loader.md b/.github/issues/022-directory-loader.md
new file mode 100644
index 0000000..ea110ce
--- /dev/null
+++ b/.github/issues/022-directory-loader.md
@@ -0,0 +1,46 @@
+---
+title: "DirectoryLoader: ingest a whole folder with per-extension loader dispatch"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+Add `DirectoryLoader` that walks a directory (optionally recursive, with glob filtering) and delegates each file to the right loader by extension, returning the concatenated `list[Document]`.
+
+```python
+loader = DirectoryLoader(
+    loaders={".txt": TextFileLoader(), ".md": MarkdownLoader(), ".pdf": PDFLoader()},
+    glob="**/*",
+    recursive=True,
+    on_error="skip",   # or "raise"
+)
+pipeline = RAGPipeline(loader=loader, ...)
+pipeline.ingest("./knowledge_base")
+```
+
+## Motivation
+
+Today `RAGPipeline.ingest()` takes a single file path, so indexing a corpus means writing a loop by hand and choosing loaders manually. This is the single most requested convenience in every RAG library.
+
+## Acceptance criteria
+
+- [ ] Class `DirectoryLoader(DocumentLoader)` in `ragframework/document/loaders.py`
+- [ ] Sensible default `loaders` mapping (`.txt`, `.md`, `.markdown`, `.pdf` when `pypdf` is importable) built lazily so importing the module never requires optional deps
+- [ ] Files with no matching loader are skipped (and counted); `on_error="raise"` re-raises as `LoaderError` with the offending path
+- [ ] `source` must be an existing directory, otherwise `LoaderError`
+- [ ] Deterministic ordering (sorted paths) so chunk ids are stable across runs
+- [ ] Each `Document.metadata` includes `"relative_path"` from the root directory
+- [ ] Tests using `tmp_path` with mixed extensions, nested folders, an unreadable file with both `on_error` modes
+- [ ] Exported from `ragframework/document/__init__.py`; `CHANGELOG.md` updated
+
+## Files to touch
+
+- `ragframework/document/loaders.py`
+- `ragframework/document/__init__.py`
+- `tests/test_document/test_loaders.py`
+
+## Resources
+
+- [`Path.rglob`](https://docs.python.org/3/library/pathlib.html#pathlib.Path.rglob)
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/issues/023-html-loader.md b/.github/issues/023-html-loader.md
new file mode 100644
index 0000000..20b682a
--- /dev/null
+++ b/.github/issues/023-html-loader.md
@@ -0,0 +1,36 @@
+---
+title: "HTMLLoader for local .html files and web URLs"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+Add `HTMLLoader` that extracts readable text from an HTML file or URL, dropping `<script>`, `<style>`, `<nav>` and similar, and returns a single `Document` with `title` in metadata.
+
+## Motivation
+
+Documentation sites, wikis and exported web pages are a primary RAG corpus. Nothing in the framework can ingest them today.
+
+## Acceptance criteria
+
+- [ ] Class `HTMLLoader(DocumentLoader)` in `ragframework/document/html.py`
+- [ ] Works with **zero extra dependencies** using `html.parser.HTMLParser` from the stdlib; if `beautifulsoup4` is installed it may be used for better results (guarded import, new `[html]` extra in `pyproject.toml`)
+- [ ] `source` may be a local path or an `http(s)://` URL (`urllib.request` with a timeout and a custom `User-Agent`); network failures raise `LoaderError`
+- [ ] Skips `script`, `style`, `noscript`, `template`, `head`; collapses whitespace via `ragframework.utils.text.normalize_whitespace`
+- [ ] Metadata: `source`, `title` (from `<title>`), `format: "html"`
+- [ ] Tests use local fixture files only — no live network calls in CI (mock `urlopen` for the URL path)
+- [ ] Exported from `ragframework/document/__init__.py`; `CHANGELOG.md` updated
+
+## Files to touch
+
+- `ragframework/document/html.py` — new
+- `ragframework/document/__init__.py`
+- `pyproject.toml` — optional `[html]` extra
+- `tests/test_document/test_html.py` — new
+
+## Resources
+
+- [`html.parser`](https://docs.python.org/3/library/html.parser.html)
+- [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/)
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/issues/024-csv-jsonl-loader.md b/.github/issues/024-csv-jsonl-loader.md
new file mode 100644
index 0000000..bdc674f
--- /dev/null
+++ b/.github/issues/024-csv-jsonl-loader.md
@@ -0,0 +1,40 @@
+---
+title: "CSVLoader and JSONLLoader for tabular / record-oriented data"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+Add two stdlib-only loaders that turn each row / record into a `Document`:
+
+```python
+CSVLoader(content_columns=["title", "body"], metadata_columns=["url", "date"], id_column="id")
+JSONLLoader(content_key="text", metadata_keys=["source"], id_key="id")
+```
+
+## Motivation
+
+FAQ exports, support tickets, product catalogues and scraped datasets almost always arrive as CSV or JSON Lines. These are the cheapest high-value loaders to add.
+
+## Acceptance criteria
+
+- [ ] `CSVLoader(DocumentLoader)` and `JSONLLoader(DocumentLoader)` in `ragframework/document/tabular.py`
+- [ ] `content_columns` / `content_key` joined with a configurable separator (default newline); missing columns raise `LoaderError` naming the column and the row number
+- [ ] Document id: the value of `id_column` / `id_key` if given, else `f"{_make_id(source)}:{row_index}"`
+- [ ] Row index and all `metadata_columns` copied into `Document.metadata`; the whole record is **not** dumped by default
+- [ ] `encoding` and `delimiter` (CSV) arguments; malformed JSON lines raise `LoaderError` with the line number
+- [ ] Tests with `tmp_path` fixtures for happy path, missing column, bad JSON line, empty file
+- [ ] Exported from `ragframework/document/__init__.py`; `CHANGELOG.md` updated
+
+## Files to touch
+
+- `ragframework/document/tabular.py` — new
+- `ragframework/document/__init__.py`
+- `tests/test_document/test_tabular.py` — new
+
+## Resources
+
+- [`csv.DictReader`](https://docs.python.org/3/library/csv.html#csv.DictReader)
+- [JSON Lines](https://jsonlines.org/)
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/025-bm25-hybrid-retriever.md b/.github/issues/025-bm25-hybrid-retriever.md
new file mode 100644
index 0000000..abb7355
--- /dev/null
+++ b/.github/issues/025-bm25-hybrid-retriever.md
@@ -0,0 +1,42 @@
+---
+title: "BM25Retriever (lexical) and HybridRetriever — requires passing query text to retrievers"
+labels: ["enhancement", "help wanted"]
+---
+
+## Description
+
+Dense retrieval alone misses exact matches (error codes, product SKUs, names). Add a lexical `BM25Retriever` and a `HybridRetriever` that fuses dense + lexical results with Reciprocal Rank Fusion.
+
+### The API problem this exposes
+
+`Retriever.retrieve(query_embedding, top_k)` receives only the vector. A lexical retriever needs the **text**. Proposed, backward-compatible change to the ABC:
+
+```python
+def retrieve(self, query_embedding: list[float], top_k: int = 5, *, query_text: str | None = None) -> list[Chunk]:
+```
+
+`RAGPipeline.query()` always passes `query_text=query`. Existing retrievers ignore it. `BM25Retriever` raises `RetrieverError` if it is `None`.
+
+## Acceptance criteria
+
+- [ ] `Retriever.retrieve` signature extended with keyword-only `query_text`; all built-in retrievers and `RAGPipeline.query()` updated; existing tests pass
+- [ ] `BM25Retriever(Retriever)` in `ragframework/retriever/bm25.py` using `rank_bm25` (new `[bm25]` extra, guarded import). Simple whitespace + lowercase tokeniser by default, injectable `tokenizer: Callable[[str], list[str]]`
+- [ ] `BM25Retriever.add()` accepts chunks **without** embeddings (document this deviation in the docstring — it is the one retriever where that is legitimate)
+- [ ] `HybridRetriever(dense: Retriever, sparse: Retriever, k: int = 60)` in `ragframework/retriever/hybrid.py` implementing RRF; fetches `top_k * 2` from each and returns the fused top_k
+- [ ] Tests: BM25 returns an exact-keyword chunk first; hybrid ranks a chunk found by both retrievers above one found by only one
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Added` / `### Changed`
+
+## Files to touch
+
+- `ragframework/base.py`
+- `ragframework/pipeline/rag.py`
+- `ragframework/retriever/bm25.py`, `ragframework/retriever/hybrid.py` — new
+- `ragframework/retriever/__init__.py`, `pyproject.toml`
+- `tests/test_retriever/test_bm25.py`, `tests/test_retriever/test_hybrid.py` — new
+
+## Resources
+
+- [rank-bm25](https://pypi.org/project/rank-bm25/)
+- [Reciprocal Rank Fusion (Cormack et al., 2009)](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf)
+
+**Estimated effort:** Large (1-2 days)
diff --git a/.github/issues/026-reranker-stage.md b/.github/issues/026-reranker-stage.md
new file mode 100644
index 0000000..30efa2e
--- /dev/null
+++ b/.github/issues/026-reranker-stage.md
@@ -0,0 +1,44 @@
+---
+title: "Add an optional Reranker stage to the pipeline (ABC + cross-encoder implementation)"
+labels: ["enhancement", "help wanted"]
+---
+
+## Description
+
+Introduce a `Reranker` ABC and wire it into `RAGPipeline.query()` between retrieval and generation:
+
+```python
+class Reranker(ABC):
+    @abstractmethod
+    def rerank(self, query: str, chunks: list[Chunk], top_k: int) -> list[Chunk]: ...
+```
+
+Pipeline flow becomes: embed query → retrieve `config.retrieve_k` (e.g. 20) → rerank to `config.top_k` (e.g. 5) → generate.
+
+## Motivation
+
+Two-stage retrieval (cheap bi-encoder recall, precise cross-encoder precision) is the standard way to lift RAG answer quality by a large margin, and it fits the framework's plug-in architecture perfectly.
+
+## Acceptance criteria
+
+- [ ] `Reranker` ABC in `ragframework/base.py`; `RerankerError` in `ragframework/exceptions.py`
+- [ ] `RAGPipeline.__init__(..., reranker: Reranker | None = None)`; `RAGConfig.retrieve_k: int | None = None` (defaults to `top_k` when no reranker is set, or `top_k * 4` when one is)
+- [ ] `CrossEncoderReranker` in `ragframework/reranker/cross_encoder.py` using `sentence_transformers.CrossEncoder` (already covered by the `[huggingface]` extra; default model `cross-encoder/ms-marco-MiniLM-L-6-v2`), guarded import following the `HuggingFaceEmbedder` pattern
+- [ ] A dependency-free `NoOpReranker` for tests
+- [ ] Sets `Chunk.score` if the retrieval-scores issue has landed, otherwise stores the rerank score in `metadata["rerank_score"]`
+- [ ] Pipeline test with a fake reranker that reverses order, asserting the generator receives the reranked list
+- [ ] `README.md` architecture section and `CHANGELOG.md` updated
+
+## Files to touch
+
+- `ragframework/base.py`, `ragframework/exceptions.py`, `ragframework/config.py`
+- `ragframework/pipeline/rag.py`
+- `ragframework/reranker/__init__.py`, `ragframework/reranker/cross_encoder.py` — new
+- `tests/test_reranker/`, `tests/test_pipeline/test_rag.py`
+
+## Resources
+
+- [Sentence Transformers cross-encoders](https://www.sbert.net/docs/cross_encoder/usage/usage.html)
+- `tests/test_embeddings/test_huggingface.py` for how to fake `sentence_transformers` in tests
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/issues/027-retriever-persistence.md b/.github/issues/027-retriever-persistence.md
new file mode 100644
index 0000000..c450038
--- /dev/null
+++ b/.github/issues/027-retriever-persistence.md
@@ -0,0 +1,41 @@
+---
+title: "Persist and reload FAISSRetriever and InMemoryRetriever indexes"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+Only `ChromaRetriever` survives a process restart. `FAISSRetriever` and `InMemoryRetriever` must re-embed the whole corpus every run. Add:
+
+```python
+retriever.save("index_dir/")
+retriever = FAISSRetriever.load("index_dir/")
+```
+
+## Motivation
+
+Embedding is the slow, expensive step (API cost or GPU time). Losing the index on exit makes the two fastest retrievers impractical beyond demos.
+
+## Acceptance criteria
+
+- [ ] `save(path: str | Path) -> None` and `@classmethod load(path) -> Self` on both classes
+- [ ] `FAISSRetriever.save` writes `index.faiss` (`faiss.write_index`) + `chunks.json` (ids, content, metadata) + `meta.json` (dimension, `m`, `ef_construction`, `ef_search`, format version)
+- [ ] `InMemoryRetriever.save` writes `matrix.npy` + `chunks.json`
+- [ ] Use JSON, **not pickle**, for chunk data (safe to load untrusted files); `np.load(..., allow_pickle=False)`
+- [ ] `load()` on a missing/corrupt directory raises `RetrieverError`; format-version mismatch raises `RetrieverError` with guidance
+- [ ] Round-trip tests with `tmp_path`: save → load → identical `len()` and identical `retrieve()` results
+- [ ] Docstrings + `examples/README.md` snippet; `CHANGELOG.md` updated
+
+## Files to touch
+
+- `ragframework/retriever/faiss.py`
+- `ragframework/retriever/in_memory.py`
+- `tests/test_retriever/test_faiss.py`, `tests/test_retriever/test_in_memory.py`
+- `examples/README.md`
+
+## Resources
+
+- [`faiss.write_index` / `read_index`](https://github.com/facebookresearch/faiss/wiki/Index-IO,-cloning-and-hyper-parameter-tuning)
+- [`numpy.save` / `numpy.load`](https://numpy.org/doc/stable/reference/generated/numpy.save.html)
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/issues/028-metadata-filtering.md b/.github/issues/028-metadata-filtering.md
new file mode 100644
index 0000000..8c28f0b
--- /dev/null
+++ b/.github/issues/028-metadata-filtering.md
@@ -0,0 +1,44 @@
+---
+title: "Metadata filtering in Retriever.retrieve()"
+labels: ["enhancement", "help wanted"]
+---
+
+## Description
+
+Allow callers to restrict retrieval to chunks whose metadata matches a filter:
+
+```python
+pipeline.query("refund policy", filter={"source": "policies.pdf"})
+retriever.retrieve(q, top_k=5, filter={"page_number": 3})
+```
+
+## Motivation
+
+Multi-tenant apps, per-document Q&A ("only answer from this file") and date-scoped search all need this. `ChromaRetriever` already stores metadata and Chroma supports `where=`, but the framework API has no way to reach it.
+
+## Proposed design
+
+- `Retriever.retrieve(..., *, filter: Mapping[str, Any] | None = None)` — keyword-only, default `None`
+- v1 semantics: exact-match AND across keys. Document that richer operators are out of scope for now
+- `InMemoryRetriever` / `FAISSRetriever`: post-filter. Because FAISS returns only `top_k` labels, over-fetch (`top_k * 4`, capped at `len(self)`) and keep the first `top_k` matches; document the limitation
+- `ChromaRetriever`: translate to a Chroma `where` clause. **Blocker:** `ChromaRetriever._metadata()` currently serialises all user metadata into a single JSON string under `_ragframework_metadata`, which Chroma cannot filter on. Store scalar keys (`str/int/float/bool`) as top-level Chroma metadata as well, keeping the JSON blob for lossless restore
+- `RAGPipeline.query(query, *, filter=None)` passes it through
+
+## Acceptance criteria
+
+- [ ] ABC, all three retrievers, and pipeline updated; `filter=None` behaviour unchanged
+- [ ] Chroma metadata storage change is backward compatible with collections written by the current code (`_restore_metadata` still works)
+- [ ] Tests per retriever: filter narrows results; filter with no matches returns `[]`; non-scalar filter values raise `RetrieverError`
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Added`
+
+## Files to touch
+
+- `ragframework/base.py`, `ragframework/pipeline/rag.py`
+- `ragframework/retriever/in_memory.py`, `faiss.py`, `chroma.py`
+- Tests for each
+
+## Resources
+
+- [Chroma `where` filters](https://docs.trychroma.com/docs/querying-collections/metadata-filtering)
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/issues/029-logging.md b/.github/issues/029-logging.md
new file mode 100644
index 0000000..a6f5fbc
--- /dev/null
+++ b/.github/issues/029-logging.md
@@ -0,0 +1,38 @@
+---
+title: "Add structured logging across pipeline stages"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+The package emits no log output at all. Add a module-level logger (`logging.getLogger("ragframework")`) and log at each pipeline stage:
+
+- `ingest`: source, number of documents loaded, number of chunks produced, embedding time, chunks indexed. `WARNING` when a source yields zero chunks (currently `ingest()` just returns `0` silently)
+- `query`: `top_k`, number of chunks retrieved, retrieval + generation time
+- Retrievers: `DEBUG` on add (count, dimension)
+
+## Motivation
+
+When retrieval returns nothing useful, users currently have no way to tell whether the document loaded empty, chunked into nothing, or the embedder returned junk. Standard-library logging with a `NullHandler` is the idiomatic, zero-cost way to give them visibility.
+
+## Acceptance criteria
+
+- [ ] `ragframework/__init__.py` attaches `logging.NullHandler()` to the `"ragframework"` logger (library best practice — never configure handlers for the user)
+- [ ] Each module uses `logger = logging.getLogger(__name__)` (so users can filter `ragframework.retriever.faiss` etc.)
+- [ ] Levels: `INFO` for stage summaries, `DEBUG` for per-batch detail, `WARNING` for empty ingest — no `print()` anywhere in `ragframework/`
+- [ ] Tests use `caplog` to assert the empty-ingest warning and the ingest summary
+- [ ] `docs/getting-started.md` (or README) shows the two-line `logging.basicConfig(level=logging.INFO)` snippet to enable output
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Added`
+
+## Files to touch
+
+- `ragframework/__init__.py`
+- `ragframework/pipeline/rag.py`
+- `ragframework/retriever/*.py`
+- `tests/test_pipeline/test_rag.py`
+
+## Resources
+
+- [Configuring logging for a library](https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library)
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/030-batch-embedding.md b/.github/issues/030-batch-embedding.md
new file mode 100644
index 0000000..733fbb9
--- /dev/null
+++ b/.github/issues/030-batch-embedding.md
@@ -0,0 +1,34 @@
+---
+title: "Batch embedding calls in RAGPipeline.ingest()"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+`RAGPipeline.ingest()` sends **all** chunk texts to `embedder.embed()` in a single call:
+
+```python
+texts = [c.content for c in all_chunks]
+embeddings = self.embedder.embed(texts)
+```
+
+A 300-page PDF split into 512-char chunks is ~3 000 texts in one request. Hosted embedding APIs reject batches this large (OpenAI caps at 2 048 inputs per request), and local models can run out of memory.
+
+## Acceptance criteria
+
+- [ ] `RAGConfig.embed_batch_size: int = 64` (validated `> 0`)
+- [ ] `ingest()` iterates `all_chunks` in batches of that size and concatenates the results; order preserved; `zip(..., strict=True)` check kept
+- [ ] A test with a fake embedder that records call sizes, asserting no call exceeds the batch size and the total count is right
+- [ ] `RAGConfig` docstring updated; `CHANGELOG.md` updated under `[Unreleased]` → `### Added`
+
+## Files to touch
+
+- `ragframework/config.py`
+- `ragframework/pipeline/rag.py` — `ingest()` (lines 96–103)
+- `tests/test_pipeline/test_rag.py`, `tests/test_config.py`
+
+## Resources
+
+- [OpenAI embeddings limits](https://platform.openai.com/docs/guides/embeddings) — relevant once #6 lands
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/031-pipeline-ergonomics.md b/.github/issues/031-pipeline-ergonomics.md
new file mode 100644
index 0000000..1103edc
--- /dev/null
+++ b/.github/issues/031-pipeline-ergonomics.md
@@ -0,0 +1,29 @@
+---
+title: "RAGPipeline ergonomics: ingest_many(), query(top_k=...) override, and RAGResponse.query"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+Three small quality-of-life gaps in the public pipeline API:
+
+1. **`ingest_many(sources: Iterable[str]) -> int`** — loop over `ingest()`, return the total chunk count. Saves every user from writing the same loop (and pairs with the `DirectoryLoader` issue).
+2. **`query(query, *, top_k: int | None = None)`** — per-call override of `config.top_k` without constructing a new pipeline.
+3. **`RAGResponse.query: str`** — the response should carry the question it answers, so callers logging or caching responses don't have to thread it through separately.
+
+## Acceptance criteria
+
+- [ ] `ingest_many()` implemented; on failure, the raised `PipelineError` message includes which source failed and how many succeeded before it
+- [ ] `query(top_k=)` implemented; `top_k <= 0` raises `PipelineError` (consistent with `RAGConfig` validation)
+- [ ] `RAGResponse` gains `query: str` (add it as the **last** field with a default of `""` so positional construction in existing code does not break)
+- [ ] Tests for all three in `tests/test_pipeline/test_rag.py`
+- [ ] README Quick Start updated to show `ingest_many`; `CHANGELOG.md` updated
+
+## Files to touch
+
+- `ragframework/pipeline/rag.py`
+- `ragframework/base.py` — `RAGResponse`
+- `tests/test_pipeline/test_rag.py`
+- `README.md`
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/032-token-chunker.md b/.github/issues/032-token-chunker.md
new file mode 100644
index 0000000..a4b7386
--- /dev/null
+++ b/.github/issues/032-token-chunker.md
@@ -0,0 +1,38 @@
+---
+title: "TokenChunker: split by model tokens instead of characters"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+Add `TokenChunker` that measures chunk size in tokens using `tiktoken`, so chunks map directly onto embedding-model and LLM context limits.
+
+```python
+TokenChunker(chunk_tokens=256, overlap_tokens=32, encoding_name="cl100k_base")
+```
+
+## Motivation
+
+Character counts are a poor proxy: 512 characters is ~128 tokens of English but ~512 tokens of CJK text or code. Every hosted embedding API bills and limits by tokens.
+
+## Acceptance criteria
+
+- [ ] Class `TokenChunker(TextChunker)` in `ragframework/document/chunkers.py`
+- [ ] Uses `tiktoken` via a new `[tokens]` extra in `pyproject.toml`; guarded import with the standard install hint
+- [ ] Encodes once, slides a token window with overlap, decodes each window back to text; same validation rules as `RecursiveChunker` (`chunk_tokens > 0`, `0 <= overlap < chunk_tokens`)
+- [ ] Chunk ids / metadata follow the existing `f"{document.id}:{i}"` + `chunk_index` convention; also store `token_count` in chunk metadata
+- [ ] Tests fake the `tiktoken` module (see how `tests/test_embeddings/test_huggingface.py` fakes `sentence_transformers`) so CI needs no download; assert no chunk exceeds `chunk_tokens`
+- [ ] Exported from `ragframework/document/__init__.py`; `CHANGELOG.md` updated
+
+## Files to touch
+
+- `ragframework/document/chunkers.py`
+- `ragframework/document/__init__.py`
+- `pyproject.toml`
+- `tests/test_document/test_chunkers.py`
+
+## Resources
+
+- [tiktoken](https://github.com/openai/tiktoken)
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/issues/033-cli.md b/.github/issues/033-cli.md
new file mode 100644
index 0000000..ac4fdd6
--- /dev/null
+++ b/.github/issues/033-cli.md
@@ -0,0 +1,42 @@
+---
+title: "Command-line interface: ragframework ingest / ragframework query"
+labels: ["enhancement", "help wanted"]
+---
+
+## Description
+
+Add a small CLI (stdlib `argparse`, no new required deps) exposed as a console script:
+
+```bash
+ragframework ingest ./docs --index ./index --embedder huggingface --retriever faiss
+ragframework query "How do I configure chunk overlap?" --index ./index --top-k 3
+ragframework --version
+```
+
+## Motivation
+
+Lets people evaluate the framework in 60 seconds without writing Python, and gives maintainers a quick smoke test. Depends on retriever persistence for `--index` to be meaningful; until then the CLI can run ingest + query in one invocation.
+
+## Acceptance criteria
+
+- [ ] `ragframework/cli.py` with `main(argv=None)`; `[project.scripts] ragframework = "ragframework.cli:main"` in `pyproject.toml`
+- [ ] Component selection by name with a small registry: `--loader {auto,text,markdown,pdf,directory}`, `--chunker {fixed,recursive,sentence}`, `--embedder {random,huggingface}`, `--retriever {memory,faiss,chroma}`, `--generator {echo}`; missing optional deps produce the standard install hint, exit code 1
+- [ ] `--chunk-size`, `--chunk-overlap`, `--top-k` map onto `RAGConfig`
+- [ ] `query` prints the answer, then sources as `[n] <id> (<source>)`; `--json` prints a machine-readable `RAGResponse`
+- [ ] `--verbose` enables `logging` at INFO (see the logging issue)
+- [ ] Tests invoke `main([...])` directly with `tmp_path` fixtures and the random/echo components; also `python -m ragframework` works (`__main__.py`)
+- [ ] README "Quick Start" gets a CLI subsection; `CHANGELOG.md` updated
+
+## Files to touch
+
+- `ragframework/cli.py`, `ragframework/__main__.py` — new
+- `pyproject.toml`
+- `tests/test_cli.py` — new
+- `README.md`
+
+## Resources
+
+- [`argparse` sub-commands](https://docs.python.org/3/library/argparse.html#sub-commands)
+- [Entry points / console scripts](https://packaging.python.org/en/latest/specifications/entry-points/)
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/issues/034-retriever-abc-len-clear.md b/.github/issues/034-retriever-abc-len-clear.md
new file mode 100644
index 0000000..1beb191
--- /dev/null
+++ b/.github/issues/034-retriever-abc-len-clear.md
@@ -0,0 +1,25 @@
+---
+title: "Promote __len__ and add clear() to the Retriever ABC"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+All three built-in retrievers implement `__len__`, but it is not part of the `Retriever` ABC, so generic code (`if len(pipeline.retriever) == 0: ...`) is not type-safe and third-party retrievers are not required to provide it. There is also no way to empty an index short of constructing a new retriever.
+
+## Acceptance criteria
+
+- [ ] `Retriever.__len__(self) -> int` declared `@abstractmethod` in `ragframework/base.py` with a docstring ("number of indexed chunks")
+- [ ] `Retriever.clear(self) -> None` declared `@abstractmethod`; implemented in `InMemoryRetriever` (reset list + matrix), `FAISSRetriever` (drop index + dimension so the next `add` rebuilds), `ChromaRetriever` (delete + recreate the collection)
+- [ ] `CONTRIBUTING.md` "Adding a New Integration" section updated to list the new required methods
+- [ ] Tests: `clear()` → `len() == 0` and `retrieve()` returns `[]`; re-`add` after clear works (FAISS dimension may differ after clear)
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Changed` (note: breaking for third-party `Retriever` subclasses)
+
+## Files to touch
+
+- `ragframework/base.py`
+- `ragframework/retriever/in_memory.py`, `faiss.py`, `chroma.py`
+- `CONTRIBUTING.md`
+- `tests/test_retriever/*`
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/035-py-typed.md b/.github/issues/035-py-typed.md
new file mode 100644
index 0000000..d56d9d3
--- /dev/null
+++ b/.github/issues/035-py-typed.md
@@ -0,0 +1,28 @@
+---
+title: "Ship a py.typed marker so downstream users get type hints (PEP 561)"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+The package is type-checked with `mypy --strict` in CI, but there is no `ragframework/py.typed` file, so mypy/pyright in **user** projects treat `ragframework` as untyped and ignore all the annotations.
+
+## Acceptance criteria
+
+- [ ] Empty file `ragframework/py.typed` added
+- [ ] `pyproject.toml`: `[tool.setuptools.package-data] ragframework = ["py.typed"]` so it is included in wheels
+- [ ] `"Typing :: Typed"` added to `classifiers`
+- [ ] Verified by building a wheel (`pip install build && python -m build`) and confirming `py.typed` is inside it (`unzip -l dist/*.whl | grep py.typed`)
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` → `### Added`
+
+## Files to touch
+
+- `ragframework/py.typed` — new (empty)
+- `pyproject.toml`
+
+## Resources
+
+- [PEP 561](https://peps.python.org/pep-0561/)
+- [setuptools package data](https://setuptools.pypa.io/en/latest/userguide/datafiles.html)
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/036-gitattributes-line-endings.md b/.github/issues/036-gitattributes-line-endings.md
new file mode 100644
index 0000000..d8c2cae
--- /dev/null
+++ b/.github/issues/036-gitattributes-line-endings.md
@@ -0,0 +1,37 @@
+---
+title: "Add .gitattributes and normalise mixed CRLF/LF line endings"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+21 tracked files have CRLF line endings (`ragframework/document/chunkers.py`, `loaders.py`, `retriever/chroma.py`, `retriever/faiss.py`, `embeddings/huggingface.py`, most tests, `CHANGELOG.md`, `CONTRIBUTING.md`, `.github/workflows/ci.yml`, …) while the rest are LF. There is no `.gitattributes`, so what gets committed depends on each contributor's `core.autocrlf` setting.
+
+## Motivation
+
+Mixed endings cause whole-file diffs, noisy PR reviews and spurious merge conflicts — especially painful with several new contributors on Windows and Linux joining at once.
+
+## Acceptance criteria
+
+- [ ] `.gitattributes` at the repo root:
+  ```
+  * text=auto eol=lf
+  *.png binary
+  *.ipynb text eol=lf
+  ```
+- [ ] Repository renormalised in a single dedicated commit (`git add --renormalize .`) so the change is easy to review and `git blame` can skip it — add that commit's SHA to a new `.git-blame-ignore-revs` file
+- [ ] `ruff` / `black` still pass; tests still pass
+- [ ] `CONTRIBUTING.md` gets one sentence: line endings are enforced by `.gitattributes`; no local config needed
+
+## Files to touch
+
+- `.gitattributes`, `.git-blame-ignore-revs` — new
+- every CRLF file (content unchanged, endings only)
+- `CONTRIBUTING.md`
+
+## Resources
+
+- [GitHub: configuring Git to handle line endings](https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings)
+- [`blame.ignoreRevsFile`](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revs-fileltfilegt)
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/037-ci-hardening.md b/.github/issues/037-ci-hardening.md
new file mode 100644
index 0000000..65a6bfd
--- /dev/null
+++ b/.github/issues/037-ci-hardening.md
@@ -0,0 +1,39 @@
+---
+title: "CI hardening: Python 3.13/3.14, format checks, lint tests/, mypy on all versions, coverage floor"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+`.github/workflows/ci.yml` currently:
+
+- tests only Python 3.10–3.12 (3.13 has been stable for a year; contributors are already on 3.14)
+- runs `ruff check ragframework/` only — `tests/` and `examples/` are never linted
+- never runs `black --check` or `isort --check-only` although both are in `[dev]` and documented in `CONTRIBUTING.md`
+- runs mypy only on 3.10
+- uploads coverage but enforces no minimum (`fail_ci_if_error: false`, no `--cov-fail-under`)
+- does not install the `[pdf]` extra, so `PDFLoader` is only exercised through a fake `pypdf`
+
+## Acceptance criteria
+
+- [ ] Matrix extended to `["3.10", "3.11", "3.12", "3.13", "3.14"]`; classifiers in `pyproject.toml` updated to match; `black`/`ruff` `target-version` lists updated
+- [ ] Separate fast `lint` job: `ruff check .` plus either `ruff format --check .` **or** `black --check . && isort --check-only .` (pick one formatter; if ruff-format, drop black/isort from `[dev]` and update `CONTRIBUTING.md`)
+- [ ] `mypy ragframework/` runs on the oldest and newest Python in the matrix
+- [ ] `pytest --cov-fail-under=85` (measure the current number first and set the floor just below it)
+- [ ] `[pdf]` added to the CI install so at least one real-`pypdf` test can run (a tiny generated PDF fixture via `pypdf.PdfWriter`)
+- [ ] `concurrency:` block added so superseded PR runs are cancelled
+- [ ] Any failures the wider lint surfaces are fixed in the same PR
+
+## Files to touch
+
+- `.github/workflows/ci.yml`
+- `pyproject.toml`
+- `CONTRIBUTING.md`
+- possibly `tests/` and `examples/` (lint fixes)
+
+## Resources
+
+- [actions/setup-python](https://github.com/actions/setup-python)
+- [pytest-cov `--cov-fail-under`](https://pytest-cov.readthedocs.io/en/latest/config.html)
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/issues/038-pre-commit-dependabot.md b/.github/issues/038-pre-commit-dependabot.md
new file mode 100644
index 0000000..2a35874
--- /dev/null
+++ b/.github/issues/038-pre-commit-dependabot.md
@@ -0,0 +1,32 @@
+---
+title: "Developer tooling: pre-commit hooks and Dependabot"
+labels: ["enhancement", "good first issue"]
+---
+
+## Description
+
+Two small additions that keep contributions consistent without maintainer nagging:
+
+1. **`.pre-commit-config.yaml`** running `ruff` (lint + format, or black/isort — match whatever the CI-hardening issue decides), `mypy`, `end-of-file-fixer`, `trailing-whitespace`, `check-yaml`, `check-toml`, `mixed-line-ending --fix=lf`
+2. **`.github/dependabot.yml`** for `pip` (weekly, grouped minor/patch) and `github-actions` (weekly)
+
+## Acceptance criteria
+
+- [ ] `.pre-commit-config.yaml` added; `pre-commit` added to `[dev]` extra
+- [ ] `pre-commit run --all-files` passes on `main` (fix anything it flags in the same PR)
+- [ ] `CONTRIBUTING.md` Development Setup: `pre-commit install` step added
+- [ ] `.github/dependabot.yml` added with the two ecosystems, `open-pull-requests-limit` set, and a `groups:` block so minor/patch bumps arrive as one PR
+
+## Files to touch
+
+- `.pre-commit-config.yaml`, `.github/dependabot.yml` — new
+- `pyproject.toml`
+- `CONTRIBUTING.md`
+
+## Resources
+
+- [pre-commit](https://pre-commit.com/)
+- [ruff-pre-commit](https://github.com/astral-sh/ruff-pre-commit)
+- [Dependabot configuration options](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file)
+
+**Estimated effort:** Small (< 2 hours)
diff --git a/.github/issues/039-version-and-release.md b/.github/issues/039-version-and-release.md
new file mode 100644
index 0000000..b607a7c
--- /dev/null
+++ b/.github/issues/039-version-and-release.md
@@ -0,0 +1,32 @@
+---
+title: "Single-source the version and add a PyPI release workflow"
+labels: ["enhancement", "help wanted"]
+---
+
+## Description
+
+The version is declared twice — `pyproject.toml` (`version = "0.1.0"`) and `ragframework/__init__.py` (`__version__ = "0.1.0"`) — and will drift. There is also no release automation; the README says "Once published to PyPI, installation will simplify to `pip install ragframework`", so publishing is the goal.
+
+## Acceptance criteria
+
+- [ ] `ragframework/__init__.py` derives `__version__` from `importlib.metadata.version("ragframework")` (with a `PackageNotFoundError` fallback of `"0.0.0+unknown"` for source checkouts that aren't installed); `pyproject.toml` remains the single source of truth
+- [ ] Test that `ragframework.__version__` matches the installed metadata
+- [ ] `.github/workflows/release.yml` triggered on `v*` tags: builds sdist + wheel with `python -m build`, runs `twine check`, publishes with **PyPI Trusted Publishing** (`pypa/gh-action-pypi-publish`, `permissions: id-token: write`, no long-lived secrets), and creates a GitHub Release with notes extracted from the matching `CHANGELOG.md` section
+- [ ] `CONTRIBUTING.md` / a short `RELEASING.md`: bump version in `pyproject.toml` → move `[Unreleased]` to a dated section → tag → push
+- [ ] Maintainer action required (not in the PR): register the project on PyPI and configure the trusted publisher for this repo/workflow
+- [ ] README install instructions updated once the first release is out
+
+## Files to touch
+
+- `ragframework/__init__.py`
+- `.github/workflows/release.yml` — new
+- `RELEASING.md` — new (or a section in `CONTRIBUTING.md`)
+- `tests/test_version.py` — new
+
+## Resources
+
+- [`importlib.metadata`](https://docs.python.org/3/library/importlib.metadata.html)
+- [Publishing to PyPI with Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/)
+- [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish)
+
+**Estimated effort:** Medium (half day)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 39896e7..7634e95 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -16,10 +16,10 @@ jobs:
         python-version: ["3.10", "3.11", "3.12"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -34,7 +34,7 @@ jobs:
         run: pytest tests/ -v --cov=ragframework --cov-report=xml
 
       - name: Upload coverage
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v7
         with:
           files: ./coverage.xml
           fail_ci_if_error: false
@@ -43,10 +43,10 @@ jobs:
     name: Type check (Python 3.10)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Python 3.10
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.10"
           cache: pip
diff --git a/.github/workflows/create-issues.yml b/.github/workflows/create-issues.yml
index cc80a03..9bb6dcc 100644
--- a/.github/workflows/create-issues.yml
+++ b/.github/workflows/create-issues.yml
@@ -10,10 +10,10 @@ jobs:
       issues: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Post issues from .github/issues/
-        uses: actions/github-script@v7
+        uses: actions/github-script@v9
         with:
           script: |
             const fs   = require('fs');
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..43e6be8
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,126 @@
+name: Release
+
+# Two ways to run:
+#   * Push a tag like v0.2.0  -> build, publish to PyPI, create a GitHub Release
+#   * "Run workflow" button   -> build and publish to TestPyPI only (dry run)
+#
+# Publishing uses PyPI Trusted Publishing (OIDC) — no API tokens or secrets.
+# One-time setup on pypi.org / test.pypi.org is described in RELEASING.md.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Check tag matches pyproject.toml version
+        if: github.ref_type == 'tag'
+        run: |
+          python - <<'EOF'
+          import os, sys, tomllib
+          with open("pyproject.toml", "rb") as f:
+              version = tomllib.load(f)["project"]["version"]
+          tag = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          if tag != version:
+              sys.exit(f"Tag v{tag} does not match pyproject.toml version {version}")
+          print(f"OK: releasing {version}")
+          EOF
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/ragframework
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.ref_type == 'tag'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ragframework
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    if: github.ref_type == 'tag'
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Extract this version's CHANGELOG section
+        run: |
+          python - <<'EOF'
+          import os, re
+          version = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          text = open("CHANGELOG.md", encoding="utf-8").read()
+          m = re.search(rf"^## \[{re.escape(version)}\][^\n]*\n(.*?)(?=^## \[|\Z)", text, re.S | re.M)
+          notes = m.group(1).strip() if m else f"Release {version}"
+          open("RELEASE_NOTES.md", "w", encoding="utf-8").write(notes + "\n")
+          print(notes)
+          EOF
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file RELEASE_NOTES.md
diff --git a/.gitignore b/.gitignore
index e791049..297a3e2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -86,3 +86,12 @@ Thumbs.db
 *.sqlite
 chroma_db/
 faiss_index/
+
+# CCE (code-context-engine)
+# CCE local cache (per-machine, not for version control)
+.cce/
+# Claude Code local settings written by cce init
+.claude/
+# .mcp.json contains absolute paths regenerated by `cce init`
+.mcp.json
+CLAUDE.md
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..c87c22a
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,32 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+        exclude: \.ipynb$
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: mixed-line-ending
+        args: [--fix=lf]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: mypy
+        language: python
+        language_version: python3.10
+        additional_dependencies:
+          - mypy>=1.10
+          - numpy==2.2.6
+        types: [python]
+        pass_filenames: false
+        args: [ragframework/]
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 486f5d1..10bfa7f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,11 +8,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- `CSVLoader` and `JSONLLoader` for loading selected record fields into documents with configurable IDs, metadata, encoding, and row/line-specific errors, using only the standard library (closes #36).
+### Fixed
+- `InMemoryRetriever` now raises `RetrieverError` for invalid vectors and dimension mismatches, validates complete batches before updating stored data, and treats empty batches as a no-op. Vector validation and normalization are shared with `FAISSRetriever` (closes #26).
+
+## [0.2.0] - 2026-09-19
+
+### Added
+- Optional reranking stage with `Reranker`, `CrossEncoderReranker`, `NoOpReranker`, and configurable pre-rerank retrieval depth (closes #38)
+- `AnthropicGenerator` for grounded answers via the Anthropic Messages API (closes #20)
 - `ChromaRetriever` for ephemeral and persistent ChromaDB-backed vector retrieval (closes #5)
 - `FAISSRetriever` for approximate cosine-similarity search with an HNSW index (closes #4)
 - `HuggingFaceEmbedder` for local embeddings with Sentence Transformers (closes #7)
+- `OpenAIGenerator` for OpenAI-powered grounded answer generation (closes #8)
+<<<<<<< HEAD
+- `RecursiveChunker` for semantics-preserving text splitting (closes #3)
+- `PDFLoader` with support for per-page and whole-file modes (closes #1)
+- `AsyncRAGPipeline` for asynchronous RAG ingestion and querying using `asyncio.to_thread()` (closes #9)
+
+### Fixed
+- Validate configured embedding dimensions during ingestion and querying (closes #29)
+
+### Changed
+- Make `embedding_dim` validation opt-in and add `RAGPipeline.from_config()` for chunk settings
+- License metadata now uses an SPDX expression (`license = "MIT"`) in `pyproject.toml`
+- Releases are published to PyPI via GitHub Actions trusted publishing (see `RELEASING.md`)
+
+=======
+- `OpenAIGenerator` for OpenAI-powered grounded answer generation (closes #8)
 - RecursiveChunker for semantics-preserving text splitting (closes #3)
 - PDFLoader with support for per-page and whole-file modes (closes #1)
+>>>>>>> d2dface (feat: add OpenAI LLM generator)
 ## [0.1.0] - 2026-03-24
 
 ### Added
@@ -33,5 +59,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Issue templates, PR template, and contributor guide
 - 10 curated Good First Issues for new contributors
 
-[Unreleased]: https://github.com/adaumsilva/RAG-framework/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/adaumsilva/RAG-framework/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/adaumsilva/RAG-framework/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/adaumsilva/RAG-framework/releases/tag/v0.1.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5976ef1..05d3a0f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -56,6 +56,21 @@ source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install -e ".[dev]"
 ```
 
+Install the Git hooks once per clone:
+
+```bash
+pre-commit install
+```
+
+The mypy hook uses an isolated Python 3.10 environment with NumPy pinned to
+the version compatible with the project's type-check target. Ensure Python
+3.10 is installed before running the hooks. Run all hooks manually when
+needed:
+
+```bash
+pre-commit run --all-files
+```
+
 To install optional extras (e.g. while adding a PDF loader):
 
 ```bash
@@ -154,7 +169,7 @@ The constraint does not change the package's runtime dependency requirements.
 
 ## Pull Request Process
 
-1. Make sure `pytest`, `ruff`, and `mypy` all pass locally.
+1. Make sure `pytest tests/ -v` and `pre-commit run --all-files` (ruff, mypy, and file hygiene hooks) both pass locally.
 2. Add or update tests to cover your changes.
 3. Update docstrings and `CHANGELOG.md` under `[Unreleased]`.
 4. Keep PRs focused — one feature or bug fix per PR.
diff --git a/README.md b/README.md
index b5c4e40..c80167b 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # RAG Framework
 
-[![PyPI version](https://img.shields.io/badge/pypi-coming%20soon-lightgrey)](https://github.com/adaumsilva/RAG-framework)
+[![PyPI version](https://img.shields.io/pypi/v/ragframework.svg)](https://pypi.org/project/ragframework/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/adaumsilva/RAG-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/adaumsilva/RAG-framework/actions/workflows/ci.yml)
@@ -66,30 +66,35 @@ A modular, extensible Python framework for building **Retrieval-Augmented Genera
   * = open contribution opportunity — see .github/GOOD_FIRST_ISSUES.md
 ```
 
+Optional reranking is supported between retrieval and generation via `Reranker`; `CrossEncoderReranker` uses the existing `[huggingface]` extra.
+
 ---
 
 ## Installation
 
-> **Note:** The package is not yet on PyPI. Install directly from GitHub:
-
 ```bash
 # Core (numpy only)
-pip install git+https://github.com/adaumsilva/RAG-framework.git
+pip install ragframework
 
 # With PDF support
-pip install "ragframework[pdf] @ git+https://github.com/adaumsilva/RAG-framework.git"
+pip install "ragframework[pdf]"
 
-# With OpenAI support
-pip install "ragframework[openai] @ git+https://github.com/adaumsilva/RAG-framework.git"
+# With HuggingFace embeddings (local, no API key)
+pip install "ragframework[huggingface]"
 
-# With HuggingFace embeddings
-pip install "ragframework[huggingface] @ git+https://github.com/adaumsilva/RAG-framework.git"
+# With a vector store
+pip install "ragframework[faiss]"
+pip install "ragframework[chromadb]"
+
+# With the Anthropic generator
+pip install "ragframework[anthropic]"
 
 # Everything
-pip install "ragframework[all] @ git+https://github.com/adaumsilva/RAG-framework.git"
+pip install "ragframework[all]"
 ```
 
-Once published to PyPI, installation will simplify to `pip install ragframework`.
+Requires Python 3.10 or newer. To install the latest unreleased code from `main`, or to
+contribute, see [CONTRIBUTING.md](CONTRIBUTING.md) for the editable-install setup.
 
 ---
 
@@ -97,18 +102,24 @@ Once published to PyPI, installation will simplify to `pip install ragframework`
 
 ```python
 from ragframework import RAGPipeline, RAGConfig
-from ragframework.document import TextFileLoader, FixedSizeChunker
+from ragframework.document import TextFileLoader
 from ragframework.embeddings import RandomEmbedder   # swap for OpenAIEmbedder
 from ragframework.retriever import InMemoryRetriever  # swap for FAISSRetriever
 from ragframework.generator import EchoGenerator      # swap for OpenAIGenerator
 
-pipeline = RAGPipeline(
+config = RAGConfig(
+    chunk_size=512,
+    chunk_overlap=64,
+    top_k=5,
+    embedding_dim=384,
+)
+
+pipeline = RAGPipeline.from_config(
+    config,
     loader=TextFileLoader(),
-    chunker=FixedSizeChunker(chunk_size=512, chunk_overlap=64),
     embedder=RandomEmbedder(dim=384),
     retriever=InMemoryRetriever(),
     generator=EchoGenerator(),
-    config=RAGConfig(top_k=5),
 )
 
 # Ingest a document
@@ -122,6 +133,38 @@ for chunk in response.source_chunks:
     print(f"  Source: {chunk.metadata.get('source')} — {chunk.content[:80]}…")
 ```
 
+### Loading CSV and JSON Lines
+
+The built-in tabular loaders need no additional dependencies. Each CSV data row
+or JSON Lines object becomes a separate document:
+
+```python
+from ragframework.document import CSVLoader, JSONLLoader
+
+csv_loader = CSVLoader(
+    content_columns=["title", "body"],
+    metadata_columns=["url", "date"],
+    id_column="id",
+)
+documents = csv_loader.load("articles.csv")
+
+jsonl_loader = JSONLLoader(content_key="text", metadata_keys=["source"], id_key="id")
+documents = jsonl_loader.load("articles.jsonl")
+```
+
+Content fields are joined with `separator="\n"`; JSONL also accepts a list of
+content keys. Both loaders accept `encoding`, and CSV accepts `delimiter`.
+Without an explicit ID field, IDs use the source path hash and zero-based row
+index. Metadata contains the file `source`, a reserved zero-based `row_index`,
+and only the selected metadata fields. Selecting a metadata field named `source`
+replaces the file path with that field's value.
+
+CSV errors identify one-based data rows (excluding the header); malformed JSON
+or missing keys identify one-based lines. JSONL requires string content and
+string or integer IDs, preserves the types of selected metadata values, and
+rejects blank lines and non-object records with `LoaderError`. Empty files
+return no documents.
+
 ### Implementing your own component
 
 ```python
@@ -147,7 +190,7 @@ Community contributions are the engine that drives this roadmap. Pick up a [Good
 | High | DOCX document loader | Open |
 | High | OpenAI embeddings integration | Open |
 | High | HuggingFace Sentence Transformers | Open |
-| High | OpenAI / Anthropic generator | Open |
+| High | OpenAI / Anthropic generator | In Progress |
 | Medium | FAISS vector store retriever | Open |
 | Medium | ChromaDB retriever integration | Open |
 | Medium | Semantic / recursive chunker | Open |
@@ -162,9 +205,10 @@ Contributions are what make open source great. Please read [CONTRIBUTING.md](CON
 
 1. Fork the repo and create a branch: `git checkout -b feat/my-feature`
 2. Install dev dependencies: `pip install -e ".[dev]"`
-3. Write your code and tests
-4. Run the suite: `pytest tests/ -v`
-5. Open a pull request
+3. Enable the Git hooks: `pre-commit install` (Python 3.10 is required for the isolated mypy hook)
+4. Write your code and tests
+5. Run the checks: `pre-commit run --all-files` and `pytest tests/ -v`
+6. Open a pull request
 
 ---
 
diff --git a/RELEASING.md b/RELEASING.md
new file mode 100644
index 0000000..e21ef26
--- /dev/null
+++ b/RELEASING.md
@@ -0,0 +1,94 @@
+# Releasing to PyPI
+
+Releases are built and published by [`.github/workflows/release.yml`](.github/workflows/release.yml)
+using [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no API tokens are stored
+anywhere. Pushing a `v*` tag publishes to PyPI; the **Run workflow** button publishes to TestPyPI.
+
+## One-time setup (maintainer)
+
+### 1. Accounts
+
+- Create accounts on <https://pypi.org> and <https://test.pypi.org> (they are separate).
+- Enable two-factor authentication on both — PyPI requires it for publishing.
+
+### 2. Register the trusted publisher on PyPI
+
+PyPI → account menu → **Publishing** → *Add a new pending publisher* → **GitHub**:
+
+| Field | Value |
+|---|---|
+| PyPI project name | `ragframework` |
+| Owner | `adaumsilva` |
+| Repository name | `RAG-framework` |
+| Workflow name | `release.yml` |
+| Environment name | `pypi` |
+
+Repeat on **test.pypi.org** with environment name `testpypi`.
+
+"Pending" means the project does not exist yet; the first successful upload creates it and
+converts the pending publisher into a normal one.
+
+### 3. Create the GitHub environments
+
+Repo → **Settings → Environments → New environment**:
+
+- `testpypi` — no protection rules needed.
+- `pypi` — tick **Required reviewers** and add yourself. Every real release will then pause for
+  one click of approval, which is a cheap guard against an accidental tag push.
+
+## Dry run against TestPyPI
+
+Repo → **Actions → Release → Run workflow** (on `main`). When it finishes:
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ ragframework
+python -c "import ragframework; print(ragframework.__version__)"
+```
+
+TestPyPI never lets you re-upload the same version, so bump the version (or accept the
+`skip-existing` no-op) if you need to test twice.
+
+## Cutting a release
+
+1. Pick the version. Follow [SemVer](https://semver.org/): new features → minor bump,
+   fixes only → patch bump, breaking API changes → major bump (or minor while `0.x`).
+2. Update the version in **both** places (until #51 single-sources it):
+   - `pyproject.toml` → `version = "X.Y.Z"`
+   - `ragframework/__init__.py` → `__version__ = "X.Y.Z"`
+3. In `CHANGELOG.md`, rename `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`, add a fresh empty
+   `## [Unreleased]` above it, and update the two link references at the bottom of the file.
+   The release workflow copies this section into the GitHub Release notes.
+4. Commit and push to `main`; wait for CI to go green.
+5. Tag and push the tag:
+
+   ```bash
+   git tag -a vX.Y.Z -m "Release X.Y.Z"
+   git push origin vX.Y.Z
+   ```
+
+6. Actions → **Release** run: the `build` job checks the tag matches `pyproject.toml`, then
+   `publish-pypi` waits for your environment approval. Approve it.
+7. Verify:
+   - <https://pypi.org/project/ragframework/> shows the new version and a rendered README
+   - `pip install ragframework==X.Y.Z` works in a clean virtualenv
+   - The GitHub Release was created with the changelog section as notes
+
+## If something goes wrong
+
+- **Tag/version mismatch** — the build job fails before anything is uploaded. Fix the version,
+  delete the tag (`git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z`), and tag again.
+- **Upload failed after tag** — PyPI never allows re-uploading a version, even a deleted one.
+  Bump to the next patch version and release again.
+- **`invalid-publisher` error** — the owner / repo / workflow filename / environment name on
+  pypi.org does not exactly match the running workflow. Check the table above.
+- **Bad release already on PyPI** — you cannot replace it. "Yank" it on pypi.org (Manage →
+  release → Options → Yank) so `pip` skips it, then publish a fixed version.
+
+## Manual fallback (no Actions)
+
+```bash
+pip install build twine
+rm -rf dist && python -m build && twine check dist/*
+twine upload dist/*          # username: __token__   password: a pypi.org API token
+```
diff --git a/docs/getting-started.md b/docs/getting-started.md
index ea8e021..40c62d4 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -477,4 +477,3 @@ Responsible for generating an answer using the query and retrieved context.
 Generator.generate(query, context)
 
 ```
-
diff --git a/examples/README.md b/examples/README.md
index cff22bc..9605516 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -21,6 +21,7 @@ matches = retriever.retrieve([0.9, 0.1], top_k=1)
 |------|-------------|
 | [basic_rag.py](basic_rag.py) | End-to-end pipeline using only built-in components (no API key needed) |
 | [basic_rag.ipynb](basic_rag.ipynb) | Interactive Jupyter notebook covering the complete RAG pipeline |
+| [anthropic_generator.py](anthropic_generator.py) | End-to-end pipeline using `AnthropicGenerator` (requires `ANTHROPIC_API_KEY`) |
 
 ## Running the examples
 
@@ -33,6 +34,14 @@ pip install -e ".[dev]"
 python examples/basic_rag.py
 ```
 
+For the Anthropic example:
+
+```bash
+pip install -e ".[dev,anthropic]"
+export ANTHROPIC_API_KEY=your-key-here
+python examples/anthropic_generator.py
+```
+
 ### Jupyter notebook
 
 Install Jupyter dependencies:
diff --git a/examples/anthropic_generator.py b/examples/anthropic_generator.py
new file mode 100644
index 0000000..bc0732d
--- /dev/null
+++ b/examples/anthropic_generator.py
@@ -0,0 +1,83 @@
+"""Anthropic-backed RAG pipeline example.
+
+Demonstrates a full ingest -> query cycle using AnthropicGenerator for
+answer synthesis. Requires the optional Anthropic dependency and an API key.
+
+Run:
+    pip install "ragframework[anthropic]"
+    set ANTHROPIC_API_KEY=your-key-here   # Windows
+    export ANTHROPIC_API_KEY=your-key-here  # macOS/Linux
+    python examples/anthropic_generator.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+# Allow running from the repo root without installing the package
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from ragframework.config import RAGConfig
+from ragframework.document.chunkers import FixedSizeChunker
+from ragframework.document.loaders import TextFileLoader
+from ragframework.embeddings.random_embedder import RandomEmbedder
+from ragframework.generator.anthropic import AnthropicGenerator
+from ragframework.pipeline.rag import RAGPipeline
+from ragframework.retriever.in_memory import InMemoryRetriever
+
+SAMPLE_TEXT = """\
+Retrieval-Augmented Generation (RAG) combines document retrieval with language
+model generation. A typical pipeline loads documents, splits them into chunks,
+embeds those chunks, retrieves the most relevant pieces for a query, and then
+asks a generator to produce a grounded answer from the retrieved context.
+"""
+
+
+def main() -> None:
+    if not os.environ.get("ANTHROPIC_API_KEY", "").strip():
+        print("ANTHROPIC_API_KEY is not set.")
+        print("Install the optional dependency with:")
+        print('    pip install "ragframework[anthropic]"')
+        print("Then set your API key, for example:")
+        print("    export ANTHROPIC_API_KEY=your-key-here")
+        raise SystemExit(0)
+
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".txt", delete=False, encoding="utf-8"
+    ) as handle:
+        handle.write(SAMPLE_TEXT)
+        tmp_path = handle.name
+
+    print(f"Sample document written to: {tmp_path}\n")
+
+    pipeline = RAGPipeline(
+        loader=TextFileLoader(),
+        chunker=FixedSizeChunker(chunk_size=200, chunk_overlap=40),
+        embedder=RandomEmbedder(dim=64, seed=42),
+        retriever=InMemoryRetriever(),
+        generator=AnthropicGenerator(model="claude-sonnet-5"),
+        config=RAGConfig(top_k=3),
+    )
+
+    n_chunks = pipeline.ingest(tmp_path)
+    print(f"Ingested {n_chunks} chunks.\n")
+
+    query = "What does a RAG pipeline do?"
+    print(f"Query: {query!r}\n")
+
+    response = pipeline.query(query)
+
+    print("Answer:")
+    print("-" * 60)
+    print(response.answer)
+    print("-" * 60)
+    print(f"\nSource chunks used: {len(response.source_chunks)}")
+
+    Path(tmp_path).unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/async_rag.py b/examples/async_rag.py
new file mode 100644
index 0000000..43536ae
--- /dev/null
+++ b/examples/async_rag.py
@@ -0,0 +1,81 @@
+
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import tempfile
+from pathlib import Path
+
+# Allow running from the repo root without installing the package
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from ragframework.config import RAGConfig
+from ragframework.document.chunkers import FixedSizeChunker
+from ragframework.document.loaders import TextFileLoader
+from ragframework.embeddings.random_embedder import RandomEmbedder
+from ragframework.generator.echo_generator import EchoGenerator
+from ragframework.pipeline.async_rag import AsyncRAGPipeline
+from ragframework.retriever.in_memory import InMemoryRetriever
+
+SAMPLE_TEXT = """\
+Retrieval-Augmented Generation (RAG) combines information retrieval with
+text generation. A typical RAG pipeline loads documents, splits them into
+chunks, creates embeddings, retrieves relevant chunks, and generates an
+answer from the retrieved context.
+
+AsyncRAGPipeline provides an asynchronous interface for the same pipeline,
+making it suitable for async applications such as FastAPI and Starlette.
+"""
+
+
+async def main() -> None:
+    # ------------------------------------------------------------------ #
+    # 1. Write a sample document to a temporary file
+    # ------------------------------------------------------------------ #
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".txt", delete=False, encoding="utf-8"
+    ) as f:
+        f.write(SAMPLE_TEXT)
+        tmp_path = f.name
+
+    print(f"Sample document written to: {tmp_path}\n")
+
+    # ------------------------------------------------------------------ #
+    # 2. Build the async pipeline
+    # ------------------------------------------------------------------ #
+    async_pipeline = AsyncRAGPipeline(
+        loader=TextFileLoader(),
+        chunker=FixedSizeChunker(chunk_size=200, chunk_overlap=40),
+        embedder=RandomEmbedder(dim=64, seed=42),
+        retriever=InMemoryRetriever(),
+        generator=EchoGenerator(),
+        config=RAGConfig(top_k=3),
+    )
+
+    # ------------------------------------------------------------------ #
+    # 3. Asynchronously ingest the document
+    # ------------------------------------------------------------------ #
+    n_chunks = await async_pipeline.async_ingest(tmp_path)
+    print(f"Ingested {n_chunks} chunks.\n")
+
+    # ------------------------------------------------------------------ #
+    # 4. Asynchronously query the pipeline
+    # ------------------------------------------------------------------ #
+    query = "What are the stages of a RAG pipeline?"
+    print(f"Query: {query!r}\n")
+
+    response = await async_pipeline.async_query(query)
+
+    print("Answer (retrieved context):")
+    print("-" * 60)
+    print(response.answer)
+    print("-" * 60)
+    print(f"\nSource chunks used: {len(response.source_chunks)}")
+
+    # Clean up
+    Path(tmp_path).unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/basic_rag.py b/examples/basic_rag.py
index 4520f05..82bcdf5 100644
--- a/examples/basic_rag.py
+++ b/examples/basic_rag.py
@@ -50,9 +50,7 @@ def main() -> None:
     # ------------------------------------------------------------------ #
     # 1. Write a sample document to a temporary file
     # ------------------------------------------------------------------ #
-    with tempfile.NamedTemporaryFile(
-        mode="w", suffix=".txt", delete=False, encoding="utf-8"
-    ) as f:
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False, encoding="utf-8") as f:
         f.write(SAMPLE_TEXT)
         tmp_path = f.name
 
diff --git a/examples/openai_rag.py b/examples/openai_rag.py
new file mode 100644
index 0000000..8191cce
--- /dev/null
+++ b/examples/openai_rag.py
@@ -0,0 +1,74 @@
+"""RAG pipeline example using OpenAI.
+
+Requires:
+    pip install -e ".[dev,openai]"
+
+Set the OPENAI_API_KEY environment variable before running.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+# Allow running from the repo root without installing the package
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from ragframework.config import RAGConfig
+from ragframework.document.chunkers import FixedSizeChunker
+from ragframework.document.loaders import TextFileLoader
+from ragframework.embeddings.random_embedder import RandomEmbedder
+from ragframework.generator.openai import OpenAIGenerator
+from ragframework.pipeline.rag import RAGPipeline
+from ragframework.retriever.in_memory import InMemoryRetriever
+
+SAMPLE_TEXT = """\
+Retrieval-Augmented Generation (RAG) combines information retrieval
+with language generation. A RAG pipeline retrieves relevant document
+chunks and provides them to a language model as context.
+
+The retrieved context helps the language model produce answers grounded
+in the supplied information.
+"""
+
+
+def main() -> None:
+    if not os.getenv("OPENAI_API_KEY"):
+        raise RuntimeError("Set the OPENAI_API_KEY environment variable before running.")
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False, encoding="utf-8") as f:
+        f.write(SAMPLE_TEXT)
+        tmp_path = f.name
+
+    try:
+        pipeline = RAGPipeline(
+            loader=TextFileLoader(),
+            chunker=FixedSizeChunker(chunk_size=200, chunk_overlap=40),
+            # Replace RandomEmbedder with a real embedding implementation
+            # for meaningful retrieval.
+            embedder=RandomEmbedder(dim=64, seed=42),
+            retriever=InMemoryRetriever(),
+            generator=OpenAIGenerator(model="gpt-4o-mini"),
+            config=RAGConfig(top_k=3),
+        )
+
+        n_chunks = pipeline.ingest(tmp_path)
+        print(f"Ingested {n_chunks} chunks.\n")
+
+        query = "What is retrieval-augmented generation?"
+        response = pipeline.query(query)
+
+        print(f"Question: {query}\n")
+        print("Answer:")
+        print("-" * 60)
+        print(response.answer)
+        print("-" * 60)
+
+    finally:
+        Path(tmp_path).unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/pyproject.toml b/pyproject.toml
index 5bb249a..d93fe7e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,20 +1,20 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["setuptools>=77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "ragframework"
-version = "0.1.0"
+version = "0.2.0"
 description = "A modular, extensible Python framework for building Retrieval-Augmented Generation (RAG) pipelines"
 readme = "README.md"
-license = { file = "LICENSE" }
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [{ name = "Adam Silva", email = "adaumsilva@gmail.com" }]
 keywords = ["rag", "retrieval-augmented-generation", "llm", "nlp", "embeddings", "vector-store"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -47,10 +47,12 @@ all = [
 dev = [
     "pytest>=8.0",
     "pytest-cov>=5.0",
+    "pytest-asyncio>=0.23",
     "black>=24.0",
     "isort>=5.13",
     "ruff>=0.4",
     "mypy>=1.10",
+    "pre-commit>=3.7",
 ]
 
 [project.urls]
diff --git a/ragframework/__init__.py b/ragframework/__init__.py
index 8a1333d..e02be82 100644
--- a/ragframework/__init__.py
+++ b/ragframework/__init__.py
@@ -7,13 +7,14 @@
     Embedder,
     Generator,
     RAGResponse,
+    Reranker,
     Retriever,
     TextChunker,
 )
 from ragframework.config import RAGConfig
 from ragframework.pipeline.rag import RAGPipeline
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __all__ = [
     "__version__",
     # Data types
@@ -25,6 +26,7 @@
     "TextChunker",
     "Embedder",
     "Retriever",
+    "Reranker",
     "Generator",
     # Config
     "RAGConfig",
diff --git a/ragframework/base.py b/ragframework/base.py
index 52f15f7..cf0debc 100644
--- a/ragframework/base.py
+++ b/ragframework/base.py
@@ -139,6 +139,14 @@ def retrieve(self, query_embedding: list[float], top_k: int = 5) -> list[Chunk]:
         """
 
 
+class Reranker(ABC):
+    """Re-order retrieved chunks using the query text and chunk contents."""
+
+    @abstractmethod
+    def rerank(self, query: str, chunks: list[Chunk], top_k: int) -> list[Chunk]:
+        """Return the *top_k* most relevant chunks after reranking."""
+
+
 class Generator(ABC):
     """Generate a natural-language answer given a query and retrieved context."""
 
diff --git a/ragframework/config.py b/ragframework/config.py
index aaea264..3b33292 100644
--- a/ragframework/config.py
+++ b/ragframework/config.py
@@ -10,17 +10,21 @@ class RAGConfig:
     """Configuration for a :class:`~ragframework.pipeline.rag.RAGPipeline`.
 
     Attributes:
-        chunk_size: Target character length for each text chunk.
-        chunk_overlap: Number of overlapping characters between adjacent chunks.
-        top_k: Number of chunks to retrieve per query.
-        embedding_dim: Dimensionality of embedding vectors (must match the
-            :class:`~ragframework.base.Embedder` in use).
+        chunk_size: Target character length used by chunker ``from_config`` helpers.
+        chunk_overlap: Overlap used by chunker ``from_config`` helpers.
+        top_k: Number of chunks to keep after optional reranking.
+        embedding_dim: Optional dimensionality enforced against vectors produced by
+            the configured :class:`~ragframework.base.Embedder`. ``None`` disables
+            validation for embedders whose dimension is not known ahead of time.
+        retrieve_k: Number of candidate chunks to retrieve before reranking. When None,
+            the pipeline uses top_k without a reranker and top_k * 4 with one.
     """
 
     chunk_size: int = 512
     chunk_overlap: int = 64
     top_k: int = 5
-    embedding_dim: int = 384
+    embedding_dim: int | None = None
+    retrieve_k: int | None = None
 
     def __post_init__(self) -> None:
         if self.chunk_size <= 0:
@@ -31,5 +35,7 @@ def __post_init__(self) -> None:
             raise ValueError("chunk_overlap must be less than chunk_size")
         if self.top_k <= 0:
             raise ValueError("top_k must be positive")
-        if self.embedding_dim <= 0:
+        if self.retrieve_k is not None and self.retrieve_k <= 0:
+            raise ValueError("retrieve_k must be positive when set")
+        if self.embedding_dim is not None and self.embedding_dim <= 0:
             raise ValueError("embedding_dim must be positive")
diff --git a/ragframework/document/__init__.py b/ragframework/document/__init__.py
index 56f931a..bd5bfa8 100644
--- a/ragframework/document/__init__.py
+++ b/ragframework/document/__init__.py
@@ -3,11 +3,14 @@
 from ragframework.document.chunkers import FixedSizeChunker, RecursiveChunker, SentenceChunker
 
 from .loaders import MarkdownLoader, PDFLoader, TextFileLoader
+from .tabular import CSVLoader, JSONLLoader
 
 __all__ = [
     "TextFileLoader",
     "MarkdownLoader",
     "PDFLoader",
+    "CSVLoader",
+    "JSONLLoader",
     "FixedSizeChunker",
     "RecursiveChunker",
     "SentenceChunker",
diff --git a/ragframework/document/loaders.py b/ragframework/document/loaders.py
index f2fe7c8..9f3ee55 100644
--- a/ragframework/document/loaders.py
+++ b/ragframework/document/loaders.py
@@ -93,7 +93,10 @@ def load(self, source: str) -> list[Document]:
         try:
             from pypdf import PdfReader
         except ImportError as exc:
-            raise ImportError("PDF support requires 'ragframework[pdf]'. " "Install it with: pip install ragframework[pdf]") from exc
+            raise ImportError(
+                "PDF support requires 'ragframework[pdf]'. "
+                "Install it with: pip install ragframework[pdf]"
+            ) from exc
 
         # Open the PDF
         try:
@@ -106,9 +109,7 @@ def load(self, source: str) -> list[Document]:
         if not self.split_pages:
             # One single Document for the whole PDF
             try:
-                full_text = "\n\n".join(
-                    page.extract_text() or "" for page in reader.pages
-                )
+                full_text = "\n\n".join(page.extract_text() or "" for page in reader.pages)
             except Exception as exc:
                 raise LoaderError(f"Failed to extract text from {source}: {exc}") from exc
 
diff --git a/ragframework/document/tabular.py b/ragframework/document/tabular.py
new file mode 100644
index 0000000..88915e8
--- /dev/null
+++ b/ragframework/document/tabular.py
@@ -0,0 +1,192 @@
+"""CSV and JSON Lines document loaders using only the standard library."""
+
+from __future__ import annotations
+
+import csv
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from ragframework.base import Document, DocumentLoader
+from ragframework.document.loaders import _make_id
+from ragframework.exceptions import LoaderError
+
+
+def _document_from_record(
+    record: Mapping[str, Any],
+    source: str,
+    row_index: int,
+    location: str,
+    content_keys: list[str],
+    metadata_keys: list[str],
+    id_key: str | None,
+    separator: str,
+) -> Document:
+    required = content_keys + metadata_keys + ([id_key] if id_key is not None else [])
+    for key in required:
+        if key not in record:
+            raise LoaderError(f"Missing field '{key}' at {location} in {source}.")
+
+    parts: list[str] = []
+    for key in content_keys:
+        value = record[key]
+        if not isinstance(value, str):
+            raise LoaderError(f"Content field '{key}' at {location} in {source} must be a string.")
+        parts.append(value)
+
+    document_id = f"{_make_id(source)}:{row_index}"
+    if id_key is not None:
+        value = record[id_key]
+        if not isinstance(value, str | int) or isinstance(value, bool):
+            raise LoaderError(
+                f"ID field '{id_key}' at {location} in {source} must be a string or integer."
+            )
+        document_id = str(value)
+
+    metadata = {"source": source, **{key: record[key] for key in metadata_keys}}
+    metadata["row_index"] = row_index
+    return Document(id=document_id, content=separator.join(parts), metadata=metadata)
+
+
+class CSVLoader(DocumentLoader):
+    """Load each CSV data row as a document, using the first row as the header.
+
+    Args:
+        content_columns: Columns to join, in order, to form document content.
+        metadata_columns: Additional columns to copy into metadata. Other
+            columns are omitted. ``row_index`` is reserved for the zero-based
+            data row index; selecting ``source`` overrides the source path.
+        id_column: Column to use as the document ID. Otherwise, IDs use the
+            source path hash and zero-based data row index.
+        separator: Text between content columns (a newline by default).
+        encoding: File encoding.
+        delimiter: Single-character CSV field delimiter.
+
+    Missing fields report one-based data row numbers, excluding the header.
+    Quoted delimiters and multiline fields follow standard CSV parsing rules.
+    Empty files and header-only files produce no documents.
+    """
+
+    def __init__(
+        self,
+        content_columns: list[str],
+        metadata_columns: list[str] | None = None,
+        id_column: str | None = None,
+        *,
+        separator: str = "\n",
+        encoding: str = "utf-8",
+        delimiter: str = ",",
+    ) -> None:
+        if not content_columns:
+            raise ValueError("content_columns must not be empty.")
+        if len(delimiter) != 1 or delimiter in "\r\n":
+            raise ValueError("delimiter must be a single character other than a newline.")
+        if metadata_columns and "row_index" in metadata_columns:
+            raise ValueError("row_index is reserved for the data row index.")
+        self.content_columns = list(content_columns)
+        self.metadata_columns = list(metadata_columns or [])
+        self.id_column = id_column
+        self.separator = separator
+        self.encoding = encoding
+        self.delimiter = delimiter
+
+    def load(self, source: str) -> list[Document]:
+        """Read CSV rows, raising ``LoaderError`` for file or record errors."""
+        documents: list[Document] = []
+        try:
+            with Path(source).open(encoding=self.encoding, newline="") as stream:
+                reader = csv.DictReader(stream, delimiter=self.delimiter, strict=True)
+                for row_index, row in enumerate(reader):
+                    if None in row:
+                        raise LoaderError(f"Extra CSV fields at row {row_index + 1} in {source}.")
+                    # DictReader fills missing trailing fields with None.
+                    record = {key: value for key, value in row.items() if value is not None}
+                    documents.append(
+                        _document_from_record(
+                            record,
+                            source,
+                            row_index,
+                            f"row {row_index + 1}",
+                            self.content_columns,
+                            self.metadata_columns,
+                            self.id_column,
+                            self.separator,
+                        )
+                    )
+        except csv.Error as exc:
+            raise LoaderError(
+                f"Malformed CSV at line {reader.reader.line_num} in {source}: {exc}"
+            ) from exc
+        except (OSError, UnicodeError) as exc:
+            raise LoaderError(f"Could not read {source}: {exc}") from exc
+        return documents
+
+
+class JSONLLoader(DocumentLoader):
+    """Load one JSON object per line as a document.
+
+    Args:
+        content_key: String field to use as content, or a list of string fields
+            to join in order with ``separator``.
+        metadata_keys: Fields to copy into metadata, retaining their JSON
+            types. Other fields are omitted. ``row_index`` is reserved for the
+            zero-based line index; selecting ``source`` overrides the file path.
+        id_key: String or integer field to use as the document ID (as a string).
+            Otherwise, IDs use the source path hash and zero-based line index.
+        separator: Text between multiple content fields (a newline by default).
+        encoding: File encoding.
+
+    Empty files produce no documents. Blank lines, non-object records, and
+    malformed JSON raise ``LoaderError`` with the one-based line number.
+    """
+
+    def __init__(
+        self,
+        content_key: str | list[str] = "text",
+        metadata_keys: list[str] | None = None,
+        id_key: str | None = None,
+        *,
+        separator: str = "\n",
+        encoding: str = "utf-8",
+    ) -> None:
+        if not content_key:
+            raise ValueError("content_key must not be empty.")
+        if metadata_keys and "row_index" in metadata_keys:
+            raise ValueError("row_index is reserved for the line index.")
+        self.content_keys = [content_key] if isinstance(content_key, str) else list(content_key)
+        self.metadata_keys = list(metadata_keys or [])
+        self.id_key = id_key
+        self.separator = separator
+        self.encoding = encoding
+
+    def load(self, source: str) -> list[Document]:
+        """Read JSON objects, raising ``LoaderError`` for file or record errors."""
+        documents: list[Document] = []
+        try:
+            with Path(source).open(encoding=self.encoding) as stream:
+                for row_index, line in enumerate(stream):
+                    location = f"line {row_index + 1}"
+                    try:
+                        record = json.loads(line)
+                    except json.JSONDecodeError as exc:
+                        raise LoaderError(
+                            f"Malformed JSON at {location} in {source}: {exc}"
+                        ) from exc
+                    if not isinstance(record, dict):
+                        raise LoaderError(f"Expected a JSON object at {location} in {source}.")
+                    documents.append(
+                        _document_from_record(
+                            record,
+                            source,
+                            row_index,
+                            location,
+                            self.content_keys,
+                            self.metadata_keys,
+                            self.id_key,
+                            self.separator,
+                        )
+                    )
+        except (OSError, UnicodeError) as exc:
+            raise LoaderError(f"Could not read {source}: {exc}") from exc
+        return documents
diff --git a/ragframework/exceptions.py b/ragframework/exceptions.py
index c44e94c..0717a28 100644
--- a/ragframework/exceptions.py
+++ b/ragframework/exceptions.py
@@ -21,6 +21,10 @@ class RetrieverError(RAGFrameworkError):
     """Raised when a :class:`~ragframework.base.Retriever` fails."""
 
 
+class RerankerError(RAGFrameworkError):
+    """Raised when a reranker fails."""
+
+
 class GeneratorError(RAGFrameworkError):
     """Raised when a :class:`~ragframework.base.Generator` fails."""
 
diff --git a/ragframework/generator/__init__.py b/ragframework/generator/__init__.py
index d0642c4..cf584e8 100644
--- a/ragframework/generator/__init__.py
+++ b/ragframework/generator/__init__.py
@@ -1,5 +1,7 @@
 """Generator implementations."""
 
+from ragframework.generator.anthropic import AnthropicGenerator
 from ragframework.generator.echo_generator import EchoGenerator
+from ragframework.generator.openai import OpenAIGenerator
 
-__all__ = ["EchoGenerator"]
+__all__ = ["AnthropicGenerator", "EchoGenerator", "OpenAIGenerator"]
diff --git a/ragframework/generator/anthropic.py b/ragframework/generator/anthropic.py
new file mode 100644
index 0000000..d4684bb
--- /dev/null
+++ b/ragframework/generator/anthropic.py
@@ -0,0 +1,111 @@
+"""Anthropic Claude generator for grounded RAG answers."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ragframework.base import Chunk, Generator
+from ragframework.exceptions import GeneratorError
+
+_INSTALL_HINT = (
+    "Anthropic support requires the 'anthropic' package. "
+    "Install it with: pip install ragframework[anthropic]"
+)
+
+_DEFAULT_SYSTEM_PROMPT = (
+    "Answer the question using only the provided context. If the context is insufficient, say so."
+)
+
+
+class AnthropicGenerator(Generator):
+    """Generate answers using the Anthropic Messages API.
+
+    Args:
+        model: Anthropic model identifier (for example ``"claude-sonnet-5"``).
+        api_key: API key. Falls back to ``ANTHROPIC_API_KEY`` when omitted.
+        system_prompt: System instruction passed to the Messages API.
+        max_tokens: Maximum tokens to generate.
+
+    Raises:
+        ImportError: If the ``anthropic`` optional dependency is not installed.
+        GeneratorError: If the API key is missing or generation fails.
+    """
+
+    def __init__(
+        self,
+        model: str,
+        api_key: str | None = None,
+        system_prompt: str = _DEFAULT_SYSTEM_PROMPT,
+        max_tokens: int = 1024,
+    ) -> None:
+        try:
+            from anthropic import Anthropic
+        except ImportError as exc:
+            raise ImportError(_INSTALL_HINT) from exc
+
+        resolved_key = (api_key or os.environ.get("ANTHROPIC_API_KEY") or "").strip()
+        if not resolved_key:
+            raise GeneratorError(
+                "No API key provided. Pass `api_key` or set the "
+                "`ANTHROPIC_API_KEY` environment variable."
+            )
+
+        self.model = model
+        self.system_prompt = system_prompt
+        self.max_tokens = max_tokens
+        try:
+            self._client: Any = Anthropic(api_key=resolved_key)
+        except Exception as exc:
+            raise GeneratorError("Could not create Anthropic client.") from exc
+
+    def generate(self, query: str, context: list[Chunk]) -> str:
+        """Generate an answer for *query* using retrieved *context* chunks."""
+        user_message = self._build_user_message(query, context)
+        try:
+            response = self._client.messages.create(
+                model=self.model,
+                max_tokens=self.max_tokens,
+                system=self.system_prompt,
+                messages=[{"role": "user", "content": user_message}],
+            )
+        except Exception as exc:
+            raise GeneratorError("Anthropic API call failed.") from exc
+
+        try:
+            return self._extract_text(response)
+        except GeneratorError:
+            raise
+        except Exception as exc:
+            raise GeneratorError("Could not read Anthropic response.") from exc
+
+    @staticmethod
+    def _build_user_message(query: str, context: list[Chunk]) -> str:
+        if context:
+            numbered = "\n\n".join(
+                f"[{index + 1}] {chunk.content}" for index, chunk in enumerate(context)
+            )
+            return (
+                "Use the following context to answer the question.\n\n"
+                f"Context:\n{numbered}\n\n"
+                f"Question: {query}"
+            )
+        return f"Use the following context to answer the question.\n\nContext:\n\nQuestion: {query}"
+
+    @staticmethod
+    def _extract_text(response: Any) -> str:
+        content = getattr(response, "content", None)
+        if not content:
+            raise GeneratorError("Anthropic response contained no content blocks.")
+
+        text_parts: list[str] = []
+        for block in content:
+            if getattr(block, "type", None) == "text":
+                text = getattr(block, "text", None)
+                if isinstance(text, str) and text:
+                    text_parts.append(text)
+
+        if not text_parts:
+            raise GeneratorError("Anthropic response contained no text blocks.")
+
+        return "".join(text_parts)
diff --git a/ragframework/generator/openai.py b/ragframework/generator/openai.py
new file mode 100644
index 0000000..4a6ec82
--- /dev/null
+++ b/ragframework/generator/openai.py
@@ -0,0 +1,113 @@
+"""OpenAI-powered LLM generator."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ragframework.base import Chunk, Generator
+from ragframework.exceptions import GeneratorError
+
+
+class OpenAIGenerator(Generator):
+    """Generate answers using the OpenAI Chat Completions API.
+
+    Args:
+        model: OpenAI chat model to use.
+        api_key: OpenAI API key. Falls back to the ``OPENAI_API_KEY``
+            environment variable when not provided.
+        system_prompt: System instruction used to ground the answer in
+            retrieved context.
+        max_tokens: Maximum number of tokens in the generated response.
+
+    Raises:
+        GeneratorError: If the OpenAI client cannot be initialized or the
+            API request fails.
+    """
+
+    def __init__(
+        self,
+        model: str = "gpt-4o-mini",
+        api_key: str | None = None,
+        system_prompt: str = (
+            "You are a helpful assistant. Answer the user's question using "
+            "the provided context. If the context does not contain enough "
+            "information to answer, say so clearly."
+        ),
+        max_tokens: int = 512,
+    ) -> None:
+
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise ImportError(
+                "OpenAI support requires 'ragframework[openai]'. "
+                "Install it with: pip install ragframework[openai]"
+            ) from exc
+
+        resolved_api_key = (api_key or os.environ.get("OPENAI_API_KEY") or "").strip()
+
+        if not resolved_api_key:
+            raise GeneratorError(
+                "No API key provided. Pass `api_key` or set the "
+                "`OPENAI_API_KEY` environment variable."
+            )
+
+        self.model = model
+        self.system_prompt = system_prompt
+        self.max_tokens = max_tokens
+
+        try:
+            self._client: Any = OpenAI(api_key=resolved_api_key)
+        except Exception as exc:
+            raise GeneratorError(f"Could not initialize OpenAI client: {exc}") from exc
+
+    def generate(self, query: str, context: list[Chunk]) -> str:
+        """Generate an answer from the query and retrieved context.
+
+        Args:
+            query: The user's question.
+            context: Retrieved chunks used to ground the answer.
+
+        Returns:
+            The generated answer text.
+
+        Raises:
+            GeneratorError: If the OpenAI API request fails or returns
+                an unexpected response.
+        """
+        formatted_context = self._format_context(context)
+
+        user_prompt = f"Context:\n{formatted_context}\n\nQuestion:\n{query}"
+
+        try:
+            response: Any = self._client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": self.system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+                max_tokens=self.max_tokens,
+            )
+
+            answer = response.choices[0].message.content
+
+            if not answer:
+                raise GeneratorError("OpenAI returned an empty response.")
+
+            return str(answer)
+
+        except GeneratorError:
+            raise
+        except Exception as exc:
+            raise GeneratorError(f"OpenAI generation failed: {exc}") from exc
+
+    @staticmethod
+    def _format_context(context: list[Chunk]) -> str:
+        """Format retrieved chunks as numbered context."""
+        if not context:
+            return "No context was retrieved."
+
+        return "\n\n".join(
+            f"[Chunk {index}]\n{chunk.content}" for index, chunk in enumerate(context, start=1)
+        )
diff --git a/ragframework/pipeline/__init__.py b/ragframework/pipeline/__init__.py
index d287a24..da919db 100644
--- a/ragframework/pipeline/__init__.py
+++ b/ragframework/pipeline/__init__.py
@@ -1,5 +1,6 @@
 """RAG pipeline orchestration."""
 
+from ragframework.pipeline.async_rag import AsyncRAGPipeline
 from ragframework.pipeline.rag import RAGPipeline
 
-__all__ = ["RAGPipeline"]
+__all__ = ["AsyncRAGPipeline", "RAGPipeline"]
diff --git a/ragframework/pipeline/async_rag.py b/ragframework/pipeline/async_rag.py
new file mode 100644
index 0000000..03fda16
--- /dev/null
+++ b/ragframework/pipeline/async_rag.py
@@ -0,0 +1,58 @@
+"""Async wrapper for the RAG pipeline."""
+
+from __future__ import annotations
+
+import asyncio
+
+from ragframework.base import (
+    DocumentLoader,
+    Embedder,
+    Generator,
+    RAGResponse,
+    Retriever,
+    TextChunker,
+)
+from ragframework.config import RAGConfig
+from ragframework.pipeline.rag import RAGPipeline
+
+
+class AsyncRAGPipeline:
+    """Async interface for RAGPipeline using asyncio.to_thread()."""
+
+    def __init__(
+        self,
+        loader: DocumentLoader,
+        chunker: TextChunker,
+        embedder: Embedder,
+        retriever: Retriever,
+        generator: Generator,
+        config: RAGConfig | None = None,
+    ) -> None:
+        self._pipeline = RAGPipeline(
+            loader=loader,
+            chunker=chunker,
+            embedder=embedder,
+            retriever=retriever,
+            generator=generator,
+            config=config,
+        )
+
+    @classmethod
+    def from_pipeline(cls, pipeline: RAGPipeline) -> AsyncRAGPipeline:
+        """Create an async wrapper from an existing RAGPipeline."""
+        instance = cls.__new__(cls)
+        instance._pipeline = pipeline
+        return instance
+
+    @property
+    def config(self) -> RAGConfig:
+        """Return the configuration of the wrapped RAG pipeline."""
+        return self._pipeline.config
+
+    async def async_ingest(self, source: str) -> int:
+        """Asynchronously ingest a document."""
+        return await asyncio.to_thread(self._pipeline.ingest, source)
+
+    async def async_query(self, query: str) -> RAGResponse:
+        """Asynchronously query the RAG pipeline."""
+        return await asyncio.to_thread(self._pipeline.query, query)
diff --git a/ragframework/pipeline/rag.py b/ragframework/pipeline/rag.py
index 673ed4b..07c4539 100644
--- a/ragframework/pipeline/rag.py
+++ b/ragframework/pipeline/rag.py
@@ -8,10 +8,12 @@
     Embedder,
     Generator,
     RAGResponse,
+    Reranker,
     Retriever,
     TextChunker,
 )
 from ragframework.config import RAGConfig
+from ragframework.document.chunkers import FixedSizeChunker
 from ragframework.exceptions import PipelineError
 
 
@@ -46,6 +48,7 @@ class RAGPipeline:
         embedder: Converts chunk text to dense vectors.
         retriever: Indexes and searches chunks by vector similarity.
         generator: Produces a final answer given the query and retrieved chunks.
+        reranker: Optional second-stage reranker applied after retrieval.
         config: Pipeline configuration (chunk sizes, top-k, …).
     """
 
@@ -57,6 +60,7 @@ def __init__(
         retriever: Retriever,
         generator: Generator,
         config: RAGConfig | None = None,
+        reranker: Reranker | None = None,
     ) -> None:
         self.loader = loader
         self.chunker = chunker
@@ -64,6 +68,46 @@ def __init__(
         self.retriever = retriever
         self.generator = generator
         self.config = config or RAGConfig()
+        self.reranker = reranker
+
+    @classmethod
+    def from_config(
+        cls,
+        config: RAGConfig,
+        *,
+        loader: DocumentLoader,
+        embedder: Embedder,
+        retriever: Retriever,
+        generator: Generator,
+        reranker: Reranker | None = None,
+        chunker_cls: type[FixedSizeChunker] = FixedSizeChunker,
+    ) -> RAGPipeline:
+        """Build a pipeline whose chunker consumes ``config`` chunk settings.
+
+        Passing components directly to :class:`RAGPipeline` remains supported for
+        callers that need to configure a chunker independently.
+        """
+        return cls(
+            loader=loader,
+            chunker=chunker_cls.from_config(config),
+            embedder=embedder,
+            retriever=retriever,
+            generator=generator,
+            config=config,
+            reranker=reranker,
+        )
+
+    def _validate_embedding_dimension(self, embedding: list[float]) -> None:
+        expected = self.config.embedding_dim
+        if expected is None:
+            return
+
+        actual = len(embedding)
+        if actual != expected:
+            raise PipelineError(
+                f"Embedder produced {actual}-dim vectors but "
+                f"RAGConfig.embedding_dim is {expected}"
+            )
 
     def ingest(self, source: str) -> int:
         """Load, chunk, embed, and index a document.
@@ -99,6 +143,9 @@ def ingest(self, source: str) -> int:
         except Exception as exc:
             raise PipelineError(f"Embedding failed: {exc}") from exc
 
+        for embedding in embeddings:
+            self._validate_embedding_dimension(embedding)
+
         for chunk, emb in zip(all_chunks, embeddings, strict=True):
             chunk.embedding = emb
 
@@ -127,11 +174,25 @@ def query(self, query: str) -> RAGResponse:
         except Exception as exc:
             raise PipelineError(f"Query embedding failed: {exc}") from exc
 
+        self._validate_embedding_dimension(query_embedding)
+
+        retrieve_k = self.config.retrieve_k
+        if retrieve_k is None:
+            retrieve_k = self.config.top_k * 4 if self.reranker is not None else self.config.top_k
+
         try:
-            chunks = self.retriever.retrieve(query_embedding, top_k=self.config.top_k)
+            chunks = self.retriever.retrieve(query_embedding, top_k=retrieve_k)
         except Exception as exc:
             raise PipelineError(f"Retrieval failed: {exc}") from exc
 
+        if self.reranker is not None:
+            try:
+                chunks = self.reranker.rerank(query, chunks, top_k=self.config.top_k)
+            except Exception as exc:
+                raise PipelineError(f"Reranking failed: {exc}") from exc
+        else:
+            chunks = chunks[: self.config.top_k]
+
         try:
             answer = self.generator.generate(query, chunks)
         except Exception as exc:
diff --git a/ragframework/reranker/__init__.py b/ragframework/reranker/__init__.py
new file mode 100644
index 0000000..e7d35cc
--- /dev/null
+++ b/ragframework/reranker/__init__.py
@@ -0,0 +1,6 @@
+"""Reranker implementations."""
+
+from ragframework.reranker.cross_encoder import CrossEncoderReranker
+from ragframework.reranker.noop import NoOpReranker
+
+__all__ = ["CrossEncoderReranker", "NoOpReranker"]
diff --git a/ragframework/reranker/cross_encoder.py b/ragframework/reranker/cross_encoder.py
new file mode 100644
index 0000000..a0f12bb
--- /dev/null
+++ b/ragframework/reranker/cross_encoder.py
@@ -0,0 +1,37 @@
+"""Sentence Transformers cross-encoder reranker."""
+
+from __future__ import annotations
+
+from ragframework.base import Chunk, Reranker
+from ragframework.exceptions import RerankerError
+
+
+class CrossEncoderReranker(Reranker):
+    def __init__(
+        self,
+        model_name: str = "cross-encoder/ms-marco-MiniLM-L-6-v2",
+        device: str | None = None,
+    ) -> None:
+        try:
+            from sentence_transformers import CrossEncoder
+        except ImportError as exc:
+            raise ImportError(
+                "Cross-encoder reranking requires 'ragframework[huggingface]'"
+            ) from exc
+        try:
+            self._model = CrossEncoder(model_name, device=device)
+        except Exception as exc:
+            raise RerankerError(f"Could not load reranker model: {exc}") from exc
+
+    def rerank(self, query: str, chunks: list[Chunk], top_k: int) -> list[Chunk]:
+        if not chunks:
+            return []
+
+        try:
+            scores = self._model.predict([(query, chunk.content) for chunk in chunks])
+        except Exception as exc:
+            raise RerankerError(f"Could not rerank chunks: {exc}") from exc
+        ranked = sorted(zip(chunks, scores, strict=True), key=lambda item: item[1], reverse=True)
+        for chunk, score in ranked[:top_k]:
+            chunk.metadata["rerank_score"] = float(score)
+        return [chunk for chunk, _ in ranked[:top_k]]
diff --git a/ragframework/reranker/noop.py b/ragframework/reranker/noop.py
new file mode 100644
index 0000000..57a88f4
--- /dev/null
+++ b/ragframework/reranker/noop.py
@@ -0,0 +1,8 @@
+"""No-op reranker."""
+
+from ragframework.base import Chunk, Reranker
+
+
+class NoOpReranker(Reranker):
+    def rerank(self, query: str, chunks: list[Chunk], top_k: int) -> list[Chunk]:
+        return chunks[:top_k]
diff --git a/ragframework/retriever/chroma.py b/ragframework/retriever/chroma.py
index 0504bd5..0323b4d 100644
--- a/ragframework/retriever/chroma.py
+++ b/ragframework/retriever/chroma.py
@@ -48,9 +48,7 @@ def __init__(
                 name=collection_name,
             )
         except Exception as exc:
-            raise RetrieverError(
-                f"Could not initialize ChromaDB: {exc}"
-            ) from exc
+            raise RetrieverError(f"Could not initialize ChromaDB: {exc}") from exc
 
     def add(self, chunks: list[Chunk]) -> None:
         """Add embedded chunks to the ChromaDB collection."""
@@ -76,9 +74,7 @@ def add(self, chunks: list[Chunk]) -> None:
                 metadatas=[self._metadata(chunk) for chunk in chunks],
             )
         except Exception as exc:
-            raise RetrieverError(
-                f"Failed to add chunks to ChromaDB: {exc}"
-            ) from exc
+            raise RetrieverError(f"Failed to add chunks to ChromaDB: {exc}") from exc
 
     def retrieve(
         self,
@@ -98,9 +94,7 @@ def retrieve(
                 include=["documents", "metadatas"],
             )
         except Exception as exc:
-            raise RetrieverError(
-                f"Failed to query ChromaDB: {exc}"
-            ) from exc
+            raise RetrieverError(f"Failed to query ChromaDB: {exc}") from exc
 
         ids_result = result.get("ids") or []
         documents_result = result.get("documents") or []
@@ -134,7 +128,7 @@ def _metadata(cls, chunk: Chunk) -> dict[str, str]:
         metadata: dict[str, Any] = {}
 
         for key, value in chunk.metadata.items():
-            if isinstance(value, (str, int, float, bool)):
+            if isinstance(value, str | int | float | bool):
                 metadata[key] = value
             else:
                 metadata[key] = str(value)
diff --git a/ragframework/retriever/faiss.py b/ragframework/retriever/faiss.py
index 25d6a2e..8792ea7 100644
--- a/ragframework/retriever/faiss.py
+++ b/ragframework/retriever/faiss.py
@@ -15,10 +15,10 @@
 
 from ragframework.base import Chunk, Retriever
 from ragframework.exceptions import RetrieverError
+from ragframework.utils.vectors import validate_vector
 
 _INSTALL_HINT = (
-    "FAISS support requires 'ragframework[faiss]'. "
-    "Install it with: pip install ragframework[faiss]"
+    "FAISS support requires 'ragframework[faiss]'. Install it with: pip install ragframework[faiss]"
 )
 
 
@@ -72,7 +72,7 @@ def add(self, chunks: list[Chunk]) -> None:
                     f"Chunk '{chunk.id}' has no embedding. "
                     "Embed chunks before adding them to the retriever."
                 )
-            vector = self._validated_vector(chunk.embedding, f"Chunk '{chunk.id}' embedding")
+            vector = validate_vector(chunk.embedding, f"Chunk '{chunk.id}' embedding")
             if expected_dimension is None:
                 expected_dimension = int(vector.shape[0])
             elif vector.shape[0] != expected_dimension:
@@ -112,7 +112,7 @@ def retrieve(self, query_embedding: list[float], top_k: int = 5) -> list[Chunk]:
         if top_k <= 0 or self._index is None or self._dimension is None:
             return []
 
-        query = self._validated_vector(query_embedding, "Query embedding")
+        query = validate_vector(query_embedding, "Query embedding")
         if query.shape[0] != self._dimension:
             raise RetrieverError(
                 f"Query embedding has dimension {query.shape[0]}; expected {self._dimension}."
@@ -128,21 +128,6 @@ def retrieve(self, query_embedding: list[float], top_k: int = 5) -> list[Chunk]:
             self._chunks[int(label)] for label in labels[0] if 0 <= int(label) < len(self._chunks)
         ]
 
-    @staticmethod
-    def _validated_vector(values: list[float], label: str) -> np.ndarray[Any, np.dtype[np.float32]]:
-        try:
-            vector = np.asarray(values, dtype=np.float32)
-        except (TypeError, ValueError) as exc:
-            raise RetrieverError(f"{label} must contain only numeric values.") from exc
-        if vector.ndim != 1 or vector.size == 0:
-            raise RetrieverError(f"{label} must be a non-empty one-dimensional vector.")
-        if not np.isfinite(vector).all():
-            raise RetrieverError(f"{label} must contain only finite values.")
-        norm = float(np.linalg.norm(vector))
-        if not np.isfinite(norm) or norm == 0.0:
-            raise RetrieverError(f"{label} must not be a zero vector.")
-        return np.ascontiguousarray(vector / norm, dtype=np.float32)
-
     def __len__(self) -> int:
         """Return the number of indexed chunks."""
         return len(self._chunks)
diff --git a/ragframework/retriever/in_memory.py b/ragframework/retriever/in_memory.py
index 23c734d..b1f31f9 100644
--- a/ragframework/retriever/in_memory.py
+++ b/ragframework/retriever/in_memory.py
@@ -8,6 +8,7 @@
 
 from ragframework.base import Chunk, Retriever
 from ragframework.exceptions import RetrieverError
+from ragframework.utils.vectors import validate_vector
 
 
 class InMemoryRetriever(Retriever):
@@ -21,26 +22,55 @@ class InMemoryRetriever(Retriever):
     def __init__(self) -> None:
         self._chunks: list[Chunk] = []
         self._matrix: np.ndarray[Any, Any] | None = None  # shape (N, dim)
+        self._dimension: int | None = None
 
     def add(self, chunks: list[Chunk]) -> None:
+        """Validate and normalize a batch before changing the stored chunks.
+
+        An empty batch is a no-op. Invalid vectors or inconsistent dimensions
+        raise ``RetrieverError`` without adding any part of the batch.
+        """
+        if not chunks:
+            return
+
+        expected_dimension = self._dimension
+        vectors: list[np.ndarray[Any, np.dtype[np.float32]]] = []
         for chunk in chunks:
             if chunk.embedding is None:
                 raise RetrieverError(
                     f"Chunk '{chunk.id}' has no embedding. "
                     "Embed chunks before adding them to the retriever."
                 )
+            vector = validate_vector(chunk.embedding, f"Chunk '{chunk.id}' embedding")
+            if expected_dimension is None:
+                expected_dimension = int(vector.shape[0])
+            elif vector.shape[0] != expected_dimension:
+                raise RetrieverError(
+                    f"Chunk '{chunk.id}' embedding has dimension {vector.shape[0]}; "
+                    f"expected {expected_dimension}."
+                )
+            vectors.append(vector)
+
+        matrix = np.stack(vectors)
+        if self._matrix is not None:
+            matrix = np.concatenate((self._matrix, matrix))
+
+        self._matrix = matrix
+        self._dimension = expected_dimension
         self._chunks.extend(chunks)
-        vectors = np.array([c.embedding for c in self._chunks], dtype=np.float32)
-        norms = np.linalg.norm(vectors, axis=1, keepdims=True)
-        norms = np.where(norms == 0, 1.0, norms)
-        self._matrix = vectors / norms
 
     def retrieve(self, query_embedding: list[float], top_k: int = 5) -> list[Chunk]:
+        """Rank chunks by cosine similarity, returning an empty list for an empty index.
+
+        Invalid query vectors or dimensions raise ``RetrieverError``.
+        """
         if not self._chunks or self._matrix is None:
             return []
-        q = np.array(query_embedding, dtype=np.float32)
-        norm = np.linalg.norm(q) or 1.0
-        q = q / norm
+        q = validate_vector(query_embedding, "Query embedding")
+        if q.shape[0] != self._dimension:
+            raise RetrieverError(
+                f"Query embedding has dimension {q.shape[0]}; expected {self._dimension}."
+            )
         scores: np.ndarray[Any, Any] = self._matrix @ q
         k = min(top_k, len(self._chunks))
         top_indices = np.argpartition(scores, -k)[-k:]
diff --git a/ragframework/utils/__init__.py b/ragframework/utils/__init__.py
index aad8e4d..444b609 100644
--- a/ragframework/utils/__init__.py
+++ b/ragframework/utils/__init__.py
@@ -1,5 +1,6 @@
 """Shared utility functions."""
 
 from ragframework.utils.text import normalize_whitespace, truncate, word_count
+from ragframework.utils.vectors import validate_vector
 
-__all__ = ["normalize_whitespace", "truncate", "word_count"]
+__all__ = ["normalize_whitespace", "truncate", "validate_vector", "word_count"]
diff --git a/ragframework/utils/vectors.py b/ragframework/utils/vectors.py
new file mode 100644
index 0000000..796b520
--- /dev/null
+++ b/ragframework/utils/vectors.py
@@ -0,0 +1,29 @@
+"""Shared validation and normalization for retriever vectors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ragframework.exceptions import RetrieverError
+
+
+def validate_vector(values: list[float], label: str) -> np.ndarray[Any, np.dtype[np.float32]]:
+    """Return a contiguous, L2-normalized float32 vector.
+
+    Raise ``RetrieverError`` with the supplied label for non-numeric, empty,
+    multidimensional, non-finite, or zero-norm vectors.
+    """
+    try:
+        vector = np.asarray(values, dtype=np.float32)
+    except (TypeError, ValueError) as exc:
+        raise RetrieverError(f"{label} must contain only numeric values.") from exc
+    if vector.ndim != 1 or vector.size == 0:
+        raise RetrieverError(f"{label} must be a non-empty one-dimensional vector.")
+    if not np.isfinite(vector).all():
+        raise RetrieverError(f"{label} must contain only finite values.")
+    norm = float(np.linalg.norm(vector))
+    if not np.isfinite(norm) or norm == 0.0:
+        raise RetrieverError(f"{label} must not be a zero vector.")
+    return np.ascontiguousarray(vector / norm, dtype=np.float32)
diff --git a/tests/conftest.py b/tests/conftest.py
index 470205c..c0ccab0 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -7,10 +7,7 @@
 from ragframework.base import Chunk, Document
 from ragframework.config import RAGConfig
 from ragframework.document.chunkers import FixedSizeChunker
-from ragframework.document.loaders import TextFileLoader
 from ragframework.embeddings.random_embedder import RandomEmbedder
-from ragframework.generator.echo_generator import EchoGenerator
-from ragframework.retriever.in_memory import InMemoryRetriever
 
 
 @pytest.fixture()
@@ -33,7 +30,7 @@ def embedded_chunks(sample_chunks: list[Chunk]) -> list[Chunk]:
     embedder = RandomEmbedder(dim=16, seed=42)
     texts = [c.content for c in sample_chunks]
     embeddings = embedder.embed(texts)
-    for chunk, emb in zip(sample_chunks, embeddings):
+    for chunk, emb in zip(sample_chunks, embeddings, strict=True):
         chunk.embedding = emb
     return sample_chunks
 
diff --git a/tests/test_config.py b/tests/test_config.py
index 6d1dfeb..8ef2078 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -10,7 +10,8 @@ def test_defaults():
     assert cfg.chunk_size == 512
     assert cfg.chunk_overlap == 64
     assert cfg.top_k == 5
-    assert cfg.embedding_dim == 384
+    assert cfg.embedding_dim is None
+    assert cfg.retrieve_k is None
 
 
 def test_custom_values():
@@ -19,6 +20,12 @@ def test_custom_values():
     assert cfg.top_k == 3
 
 
+def test_positional_arguments_preserve_embedding_dim():
+    cfg = RAGConfig(512, 64, 5, 16)
+    assert cfg.embedding_dim == 16
+    assert cfg.retrieve_k is None
+
+
 def test_invalid_chunk_size():
     with pytest.raises(ValueError, match="chunk_size"):
         RAGConfig(chunk_size=0)
@@ -37,3 +44,13 @@ def test_overlap_must_be_less_than_chunk_size():
 def test_invalid_top_k():
     with pytest.raises(ValueError, match="top_k"):
         RAGConfig(top_k=0)
+
+
+def test_invalid_embedding_dim():
+    with pytest.raises(ValueError, match="embedding_dim"):
+        RAGConfig(embedding_dim=0)
+
+
+def test_invalid_retrieve_k():
+    with pytest.raises(ValueError, match="retrieve_k"):
+        RAGConfig(retrieve_k=0)
diff --git a/tests/test_document/test_loaders.py b/tests/test_document/test_loaders.py
index 90620c9..a30aebb 100644
--- a/tests/test_document/test_loaders.py
+++ b/tests/test_document/test_loaders.py
@@ -6,7 +6,7 @@
 
 import pytest
 
-from ragframework.document.loaders import MarkdownLoader, TextFileLoader, PDFLoader
+from ragframework.document.loaders import MarkdownLoader, PDFLoader, TextFileLoader
 from ragframework.exceptions import LoaderError
 
 
diff --git a/tests/test_document/test_tabular.py b/tests/test_document/test_tabular.py
new file mode 100644
index 0000000..dff94ee
--- /dev/null
+++ b/tests/test_document/test_tabular.py
@@ -0,0 +1,231 @@
+"""File-based tests for CSV and JSON Lines document loaders."""
+
+import json
+
+import pytest
+
+from ragframework.base import DocumentLoader
+from ragframework.document import CSVLoader, JSONLLoader
+from ragframework.document.loaders import _make_id
+from ragframework.exceptions import LoaderError
+
+
+@pytest.fixture(params=["csv", "jsonl"])
+def loader(request):
+    return CSVLoader(["text"]) if request.param == "csv" else JSONLLoader()
+
+
+@pytest.mark.parametrize("line_ending", ["\n", "\r\n"])
+def test_csv_selected_fields_and_quoted_multiline_content(tmp_path, line_ending):
+    path = tmp_path / "records.csv"
+    contents = (
+        "id,title,body,url,private\n"
+        'a,"Hello, world","First line\nSecond line",https://example.com,a secret\n'
+        "b,Another,Record,https://example.org,another secret\n"
+    )
+    path.write_bytes(contents.replace("\n", line_ending).encode("utf-8"))
+    loader = CSVLoader(["title", "body"], metadata_columns=["url"], id_column="id")
+
+    docs = loader.load(str(path))
+
+    assert isinstance(loader, DocumentLoader)
+    assert [doc.id for doc in docs] == ["a", "b"]
+    assert [doc.content for doc in docs] == [
+        f"Hello, world\nFirst line{line_ending}Second line",
+        "Another\nRecord",
+    ]
+    assert docs[0].metadata == {"source": str(path), "row_index": 0, "url": "https://example.com"}
+    assert docs[1].metadata == {"source": str(path), "row_index": 1, "url": "https://example.org"}
+
+
+def test_csv_custom_delimiter_encoding_and_separator(tmp_path):
+    path = tmp_path / "records.csv"
+    path.write_text("title;body\ncafé;crème\n", encoding="latin-1")
+    docs = CSVLoader(["title", "body"], delimiter=";", separator=" | ", encoding="latin-1").load(
+        str(path)
+    )
+    assert docs[0].content == "café | crème"
+
+
+def test_jsonl_selected_metadata_preserves_types_and_explicit_ids(tmp_path):
+    path = tmp_path / "records.jsonl"
+    records = [
+        {"id": 0, "text": "First", "source": "export", "tags": ["faq"], "extra": "private"},
+        {"id": "second", "text": "Second", "source": "web", "tags": None},
+    ]
+    path.write_text("\n".join(json.dumps(row) for row in records), encoding="utf-8")
+    loader = JSONLLoader(metadata_keys=["source", "tags"], id_key="id")
+
+    docs = loader.load(str(path))
+
+    assert isinstance(loader, DocumentLoader)
+    assert [doc.id for doc in docs] == ["0", "second"]
+    assert [doc.content for doc in docs] == ["First", "Second"]
+    assert docs[0].metadata == {"source": "export", "tags": ["faq"], "row_index": 0}
+    assert docs[1].metadata == {"source": "web", "tags": None, "row_index": 1}
+
+
+@pytest.mark.parametrize("separator", ["\n", " | "])
+def test_jsonl_multiple_content_keys_and_encoding(tmp_path, separator):
+    path = tmp_path / "records.jsonl"
+    path.write_text('{"title":"café","body":"crème"}\n', encoding="latin-1")
+    docs = JSONLLoader(content_key=["title", "body"], separator=separator, encoding="latin-1").load(
+        str(path)
+    )
+    assert docs[0].content == separator.join(["café", "crème"])
+
+
+def test_default_ids_and_metadata_are_stable(tmp_path, loader):
+    path = tmp_path / "records"
+    contents = (
+        "text,unused\nFirst,secret\nSecond,private\n"
+        if isinstance(loader, CSVLoader)
+        else '{"text":"First","unused":"secret"}\n{"text":"Second","unused":"private"}\n'
+    )
+    path.write_text(contents, encoding="utf-8")
+
+    docs = loader.load(str(path))
+
+    assert [doc.id for doc in docs] == [f"{_make_id(str(path))}:0", f"{_make_id(str(path))}:1"]
+    assert [doc.content for doc in docs] == ["First", "Second"]
+    assert [doc.metadata for doc in docs] == [
+        {"source": str(path), "row_index": 0},
+        {"source": str(path), "row_index": 1},
+    ]
+    assert loader.load(str(path)) == docs
+
+
+def test_empty_file(tmp_path, loader):
+    path = tmp_path / "empty"
+    path.write_text("", encoding="utf-8")
+    assert loader.load(str(path)) == []
+
+
+def test_csv_header_only(tmp_path):
+    path = tmp_path / "empty.csv"
+    path.write_text("text\n", encoding="utf-8")
+    assert CSVLoader(["text"]).load(str(path)) == []
+
+
+@pytest.mark.parametrize(
+    "options",
+    [
+        {"content_columns": ["missing"]},
+        {"content_columns": ["text"], "metadata_columns": ["missing"]},
+        {"content_columns": ["text"], "id_column": "missing"},
+    ],
+)
+def test_csv_missing_selected_column_reports_row(tmp_path, options):
+    path = tmp_path / "missing.csv"
+    path.write_text("text\nHello\n", encoding="utf-8")
+    with pytest.raises(LoaderError, match="Missing field 'missing' at row 1"):
+        CSVLoader(**options).load(str(path))
+
+
+def test_csv_short_row_reports_missing_value(tmp_path):
+    path = tmp_path / "short.csv"
+    path.write_text("title,body\nFirst,Complete\nSecond\n", encoding="utf-8")
+    with pytest.raises(LoaderError, match="Missing field 'body' at row 2"):
+        CSVLoader(["title", "body"]).load(str(path))
+
+
+def test_csv_explicit_empty_field_is_valid(tmp_path):
+    path = tmp_path / "blank.csv"
+    path.write_text("title,body\nTitle,\n", encoding="utf-8")
+    assert CSVLoader(["title", "body"]).load(str(path))[0].content == "Title\n"
+
+
+def test_csv_extra_fields_raise(tmp_path):
+    path = tmp_path / "extra.csv"
+    path.write_text("text\nHello,extra\n", encoding="utf-8")
+    with pytest.raises(LoaderError, match="Extra CSV fields at row 1"):
+        CSVLoader(["text"]).load(str(path))
+
+
+def test_csv_malformed_quotes_raise_loader_error(tmp_path):
+    path = tmp_path / "malformed.csv"
+    path.write_text('text\n"unterminated\n', encoding="utf-8")
+    with pytest.raises(LoaderError, match="Malformed CSV at line 2") as exc:
+        CSVLoader(["text"]).load(str(path))
+    assert exc.value.__cause__ is not None
+
+
+@pytest.mark.parametrize(
+    "options",
+    [
+        {"content_key": "missing"},
+        {"metadata_keys": ["missing"]},
+        {"id_key": "missing"},
+    ],
+)
+def test_jsonl_missing_selected_key_reports_line(tmp_path, options):
+    path = tmp_path / "missing.jsonl"
+    path.write_text('{"text":"First","missing":"present"}\n{"text":"Second"}\n', encoding="utf-8")
+    with pytest.raises(LoaderError, match="Missing field 'missing' at line 2"):
+        JSONLLoader(**options).load(str(path))
+
+
+@pytest.mark.parametrize("line", ["{broken}", "", "   "])
+def test_jsonl_malformed_or_blank_line_reports_line_number(tmp_path, line):
+    path = tmp_path / "bad.jsonl"
+    path.write_text('{"text":"Valid"}\n' + line + "\n", encoding="utf-8")
+    with pytest.raises(LoaderError, match="Malformed JSON at line 2") as exc:
+        JSONLLoader().load(str(path))
+    assert isinstance(exc.value.__cause__, json.JSONDecodeError)
+
+
+@pytest.mark.parametrize("value", [None, [], 42, "text"])
+def test_jsonl_requires_object_records(tmp_path, value):
+    path = tmp_path / "nonobject.jsonl"
+    path.write_text(json.dumps(value), encoding="utf-8")
+    with pytest.raises(LoaderError, match="Expected a JSON object at line 1"):
+        JSONLLoader().load(str(path))
+
+
+@pytest.mark.parametrize("value", [None, [], 42])
+def test_jsonl_requires_string_content(tmp_path, value):
+    path = tmp_path / "content.jsonl"
+    path.write_text(json.dumps({"text": value}), encoding="utf-8")
+    with pytest.raises(LoaderError, match="Content field 'text' at line 1 .* must be a string"):
+        JSONLLoader().load(str(path))
+
+
+@pytest.mark.parametrize("value", [None, [], {}, True])
+def test_jsonl_rejects_invalid_ids(tmp_path, value):
+    path = tmp_path / "id.jsonl"
+    path.write_text(json.dumps({"text": "Hello", "id": value}), encoding="utf-8")
+    with pytest.raises(LoaderError, match="ID field 'id' at line 1 .* must be a string or integer"):
+        JSONLLoader(id_key="id").load(str(path))
+
+
+def test_file_errors_are_wrapped(tmp_path, loader):
+    with pytest.raises(LoaderError, match="Could not read") as exc:
+        loader.load(str(tmp_path / "missing"))
+    assert isinstance(exc.value.__cause__, OSError)
+    with pytest.raises(LoaderError, match="Could not read"):
+        loader.load(str(tmp_path))
+
+
+def test_decode_errors_are_wrapped(tmp_path, loader):
+    path = tmp_path / "invalid-utf8"
+    path.write_bytes(b"\xff")
+    with pytest.raises(LoaderError, match="Could not read") as exc:
+        loader.load(str(path))
+    assert isinstance(exc.value.__cause__, UnicodeDecodeError)
+
+
+@pytest.mark.parametrize("delimiter", ["", "::", "\n", "\r"])
+def test_csv_rejects_invalid_delimiter(delimiter):
+    with pytest.raises(ValueError, match="delimiter"):
+        CSVLoader(["text"], delimiter=delimiter)
+
+
+def test_empty_content_selection_and_reserved_metadata_are_rejected():
+    with pytest.raises(ValueError, match="content_columns"):
+        CSVLoader([])
+    with pytest.raises(ValueError, match="content_key"):
+        JSONLLoader(content_key=[])
+    with pytest.raises(ValueError, match="row_index"):
+        CSVLoader(["text"], metadata_columns=["row_index"])
+    with pytest.raises(ValueError, match="row_index"):
+        JSONLLoader(metadata_keys=["row_index"])
diff --git a/tests/test_generator/test_anthropic.py b/tests/test_generator/test_anthropic.py
new file mode 100644
index 0000000..00c25ec
--- /dev/null
+++ b/tests/test_generator/test_anthropic.py
@@ -0,0 +1,249 @@
+"""Tests for the Anthropic Messages API generator."""
+
+from __future__ import annotations
+
+import builtins
+import sys
+import types
+
+import pytest
+
+from ragframework.base import Chunk, Generator
+from ragframework.exceptions import GeneratorError
+from ragframework.generator.anthropic import AnthropicGenerator
+
+
+class FakeTextBlock:
+    def __init__(self, text: str) -> None:
+        self.type = "text"
+        self.text = text
+
+
+class FakeNonTextBlock:
+    def __init__(self) -> None:
+        self.type = "tool_use"
+
+
+class FakeMessageResponse:
+    def __init__(self, content: list[object]) -> None:
+        self.content = content
+
+
+class FakeMessages:
+    def __init__(self) -> None:
+        self.calls: list[dict[str, object]] = []
+        self.create_side_effect: Exception | None = None
+        self.response_content: list[object] = [FakeTextBlock("Generated answer.")]
+
+    def create(self, **kwargs: object) -> FakeMessageResponse:
+        self.calls.append(kwargs)
+        if self.create_side_effect is not None:
+            raise self.create_side_effect
+        return FakeMessageResponse(self.response_content)
+
+
+class FakeAnthropicClient:
+    def __init__(self, api_key: str | None = None) -> None:
+        self.api_key = api_key
+        self.messages = FakeMessages()
+
+
+@pytest.fixture
+def fake_anthropic(monkeypatch: pytest.MonkeyPatch) -> list[FakeAnthropicClient]:
+    module = types.ModuleType("anthropic")
+    created_clients: list[FakeAnthropicClient] = []
+
+    def factory(*, api_key: str | None = None) -> FakeAnthropicClient:
+        client = FakeAnthropicClient(api_key=api_key)
+        created_clients.append(client)
+        return client
+
+    module.Anthropic = factory
+    monkeypatch.setitem(sys.modules, "anthropic", module)
+    return created_clients
+
+
+def _make_generator(
+    fake_anthropic: list[FakeAnthropicClient],
+    *,
+    model: str = "claude-sonnet-5",
+    api_key: str = "sk-test",
+    **kwargs: object,
+) -> tuple[AnthropicGenerator, FakeAnthropicClient]:
+    generator = AnthropicGenerator(model=model, api_key=api_key, **kwargs)
+    return generator, fake_anthropic[-1]
+
+
+def test_subclasses_generator() -> None:
+    assert issubclass(AnthropicGenerator, Generator)
+
+
+def test_successful_generation(fake_anthropic: list[FakeAnthropicClient]) -> None:
+    generator, client = _make_generator(fake_anthropic)
+    client.messages.response_content = [FakeTextBlock("Grounded answer.")]
+
+    answer = generator.generate(
+        "What is RAG?", [Chunk(id="c1", content="RAG combines retrieval and generation.")]
+    )
+
+    assert answer == "Grounded answer."
+    assert len(client.messages.calls) == 1
+
+
+def test_api_call_arguments(fake_anthropic: list[FakeAnthropicClient]) -> None:
+    generator, client = _make_generator(
+        fake_anthropic,
+        model="claude-test-model",
+        system_prompt="Stay grounded.",
+        max_tokens=256,
+    )
+
+    generator.generate("Explain embeddings.", [Chunk(id="c1", content="Vectors represent text.")])
+
+    call = client.messages.calls[0]
+    assert call["model"] == "claude-test-model"
+    assert call["max_tokens"] == 256
+    assert call["system"] == "Stay grounded."
+    messages = call["messages"]
+    assert isinstance(messages, list)
+    assert len(messages) == 1
+    assert messages[0]["role"] == "user"
+    assert isinstance(messages[0]["content"], str)
+
+
+def test_context_formatting(fake_anthropic: list[FakeAnthropicClient]) -> None:
+    generator, client = _make_generator(fake_anthropic)
+    context = [
+        Chunk(id="alpha-id", content="Alpha", metadata={"source": "a.txt"}, embedding=[1.0]),
+        Chunk(id="beta-id", content="Beta", metadata={"source": "b.txt"}, embedding=[2.0]),
+    ]
+
+    generator.generate("What happened?", context)
+
+    user_message = client.messages.calls[0]["messages"][0]["content"]
+    assert "[1] Alpha" in user_message
+    assert "[2] Beta" in user_message
+    assert user_message.index("[1] Alpha") < user_message.index("[2] Beta")
+    assert "Question: What happened?" in user_message
+    assert "alpha-id" not in user_message
+    assert "a.txt" not in user_message
+
+
+def test_empty_context_still_calls_api(fake_anthropic: list[FakeAnthropicClient]) -> None:
+    generator, client = _make_generator(fake_anthropic)
+
+    generator.generate("q", [])
+
+    assert len(client.messages.calls) == 1
+    user_message = client.messages.calls[0]["messages"][0]["content"]
+    assert "Question: q" in user_message
+    assert "[1]" not in user_message
+
+
+def test_explicit_api_key(fake_anthropic: list[FakeAnthropicClient]) -> None:
+    generator = AnthropicGenerator(model="claude-sonnet-5", api_key="sk-test")
+
+    assert fake_anthropic[-1].api_key == "sk-test"
+    assert generator.model == "claude-sonnet-5"
+
+
+def test_environment_api_key_fallback(
+    fake_anthropic: list[FakeAnthropicClient],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "env-key")
+
+    AnthropicGenerator(model="claude-sonnet-5")
+
+    assert fake_anthropic[-1].api_key == "env-key"
+
+
+def test_missing_api_key(
+    fake_anthropic: list[FakeAnthropicClient], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+
+    with pytest.raises(GeneratorError, match="No API key provided"):
+        AnthropicGenerator(model="claude-sonnet-5")
+
+    assert fake_anthropic == []
+
+
+def test_missing_dependency_has_helpful_message(monkeypatch: pytest.MonkeyPatch) -> None:
+    real_import = builtins.__import__
+
+    def fake_import(name, globals=None, locals=None, fromlist=(), level=0):
+        if name == "anthropic":
+            raise ImportError("No module named 'anthropic'")
+        return real_import(name, globals, locals, fromlist, level)
+
+    monkeypatch.delitem(sys.modules, "anthropic", raising=False)
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+
+    with pytest.raises(ImportError, match=r"ragframework\[anthropic\]"):
+        AnthropicGenerator(model="claude-sonnet-5", api_key="sk-test")
+
+
+def test_client_construction_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+    module = types.ModuleType("anthropic")
+
+    def failing_factory(*, api_key: str | None = None) -> None:
+        raise RuntimeError("client init failed")
+
+    module.Anthropic = failing_factory
+    monkeypatch.setitem(sys.modules, "anthropic", module)
+
+    with pytest.raises(GeneratorError, match="Could not create Anthropic client") as exc_info:
+        AnthropicGenerator(model="claude-sonnet-5", api_key="sk-test")
+
+    assert isinstance(exc_info.value.__cause__, RuntimeError)
+
+
+def test_api_failure(fake_anthropic: list[FakeAnthropicClient]) -> None:
+    generator, client = _make_generator(fake_anthropic)
+    client.messages.create_side_effect = RuntimeError("API offline")
+
+    with pytest.raises(GeneratorError, match="Anthropic API call failed") as exc_info:
+        generator.generate("q", [Chunk(id="c1", content="context")])
+
+    assert isinstance(exc_info.value.__cause__, RuntimeError)
+
+
+def test_multiple_text_blocks(fake_anthropic: list[FakeAnthropicClient]) -> None:
+    generator, client = _make_generator(fake_anthropic)
+    client.messages.response_content = [FakeTextBlock("Part one. "), FakeTextBlock("Part two.")]
+
+    answer = generator.generate("q", [Chunk(id="c1", content="context")])
+
+    assert answer == "Part one. Part two."
+
+
+def test_empty_response_raises_generator_error(fake_anthropic: list[FakeAnthropicClient]) -> None:
+    generator, client = _make_generator(fake_anthropic)
+    client.messages.response_content = []
+
+    with pytest.raises(GeneratorError, match="no content blocks"):
+        generator.generate("q", [Chunk(id="c1", content="context")])
+
+
+def test_non_text_response_raises_generator_error(
+    fake_anthropic: list[FakeAnthropicClient],
+) -> None:
+    generator, client = _make_generator(fake_anthropic)
+    client.messages.response_content = [FakeNonTextBlock()]
+
+    with pytest.raises(GeneratorError, match="no text blocks"):
+        generator.generate("q", [Chunk(id="c1", content="context")])
+
+
+def test_constructor_configuration(fake_anthropic: list[FakeAnthropicClient]) -> None:
+    generator = AnthropicGenerator(
+        model="custom-model",
+        api_key="sk-test",
+        system_prompt="Custom prompt.",
+        max_tokens=512,
+    )
+
+    assert generator.model == "custom-model"
+    assert generator.system_prompt == "Custom prompt."
+    assert generator.max_tokens == 512
diff --git a/tests/test_generator/test_openai.py b/tests/test_generator/test_openai.py
new file mode 100644
index 0000000..0061905
--- /dev/null
+++ b/tests/test_generator/test_openai.py
@@ -0,0 +1,236 @@
+"""Tests for the OpenAI generator."""
+
+from __future__ import annotations
+
+import builtins
+import sys
+import types
+
+import pytest
+
+from ragframework.base import Chunk, Generator
+from ragframework.exceptions import GeneratorError
+from ragframework.generator.openai import OpenAIGenerator
+
+
+class FakeOpenAIResponse:
+    def __init__(self, content: str | None) -> None:
+        self.choices = [types.SimpleNamespace(message=types.SimpleNamespace(content=content))]
+
+
+class FakeCompletions:
+    def __init__(self) -> None:
+        self.calls: list[dict[str, object]] = []
+        self.create_side_effect: Exception | None = None
+        self.response_content: str | None = "Generated answer."
+
+    def create(self, **kwargs: object) -> FakeOpenAIResponse:
+        self.calls.append(kwargs)
+        if self.create_side_effect is not None:
+            raise self.create_side_effect
+        return FakeOpenAIResponse(self.response_content)
+
+
+class FakeChat:
+    def __init__(self) -> None:
+        self.completions = FakeCompletions()
+
+
+class FakeOpenAIClient:
+    def __init__(self, api_key: str | None = None) -> None:
+        self.api_key = api_key
+        self.chat = FakeChat()
+
+
+@pytest.fixture
+def fake_openai(monkeypatch: pytest.MonkeyPatch) -> list[FakeOpenAIClient]:
+    module = types.ModuleType("openai")
+    created_clients: list[FakeOpenAIClient] = []
+
+    def factory(*, api_key: str | None = None) -> FakeOpenAIClient:
+        client = FakeOpenAIClient(api_key=api_key)
+        created_clients.append(client)
+        return client
+
+    module.OpenAI = factory
+    monkeypatch.setitem(sys.modules, "openai", module)
+    return created_clients
+
+
+def _make_generator(
+    fake_openai: list[FakeOpenAIClient],
+    *,
+    model: str = "gpt-4o-mini",
+    api_key: str = "test-key",
+    **kwargs: object,
+) -> tuple[OpenAIGenerator, FakeOpenAIClient]:
+    generator = OpenAIGenerator(model=model, api_key=api_key, **kwargs)
+    return generator, fake_openai[-1]
+
+
+def test_subclasses_generator() -> None:
+    assert issubclass(OpenAIGenerator, Generator)
+
+
+def test_successful_generation(fake_openai: list[FakeOpenAIClient]) -> None:
+    generator, client = _make_generator(fake_openai)
+    client.chat.completions.response_content = "The answer is 42."
+
+    answer = generator.generate(
+        "What is the answer?",
+        [Chunk(id="1", content="The answer is 42.")],
+    )
+
+    assert answer == "The answer is 42."
+    assert len(client.chat.completions.calls) == 1
+
+
+def test_api_call_arguments(fake_openai: list[FakeOpenAIClient]) -> None:
+    generator, client = _make_generator(
+        fake_openai,
+        model="custom-model",
+        system_prompt="Use only the supplied context.",
+        max_tokens=100,
+    )
+
+    generator.generate("Question?", [])
+
+    call = client.chat.completions.calls[0]
+
+    assert call["model"] == "custom-model"
+    assert call["max_tokens"] == 100
+
+    messages = call["messages"]
+    assert isinstance(messages, list)
+    assert len(messages) == 2
+    assert messages[0]["role"] == "system"
+    assert messages[0]["content"] == "Use only the supplied context."
+    assert messages[1]["role"] == "user"
+
+
+def test_context_formatting(fake_openai: list[FakeOpenAIClient]) -> None:
+    generator, client = _make_generator(fake_openai)
+
+    context = [
+        Chunk(id="alpha-id", content="Alpha"),
+        Chunk(id="beta-id", content="Beta"),
+    ]
+
+    generator.generate("What happened?", context)
+
+    messages = client.chat.completions.calls[0]["messages"]
+    user_message = messages[1]["content"]
+
+    assert "[Chunk 1]" in user_message
+    assert "Alpha" in user_message
+    assert "[Chunk 2]" in user_message
+    assert "Beta" in user_message
+    assert user_message.index("[Chunk 1]") < user_message.index("[Chunk 2]")
+    assert "Question:\nWhat happened?" in user_message
+
+
+def test_empty_context(fake_openai: list[FakeOpenAIClient]) -> None:
+    generator, client = _make_generator(fake_openai)
+
+    generator.generate("Question?", [])
+
+    messages = client.chat.completions.calls[0]["messages"]
+    user_message = messages[1]["content"]
+
+    assert "No context was retrieved." in user_message
+    assert "Question:\nQuestion?" in user_message
+
+
+def test_explicit_api_key(fake_openai: list[FakeOpenAIClient]) -> None:
+    generator = OpenAIGenerator(api_key="sk-test")
+
+    assert fake_openai[-1].api_key == "sk-test"
+    assert generator.model == "gpt-4o-mini"
+
+
+def test_environment_api_key_fallback(
+    fake_openai: list[FakeOpenAIClient],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "env-key")
+
+    OpenAIGenerator()
+
+    assert fake_openai[-1].api_key == "env-key"
+
+
+def test_missing_api_key(
+    fake_openai: list[FakeOpenAIClient],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    with pytest.raises(GeneratorError, match="No API key provided"):
+        OpenAIGenerator()
+
+    assert fake_openai == []
+
+
+def test_missing_dependency_has_helpful_message(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    real_import = builtins.__import__
+
+    def fake_import(name, globals=None, locals=None, fromlist=(), level=0):
+        if name == "openai":
+            raise ImportError("No module named 'openai'")
+        return real_import(name, globals, locals, fromlist, level)
+
+    monkeypatch.delitem(sys.modules, "openai", raising=False)
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+
+    with pytest.raises(ImportError, match=r"ragframework\[openai\]"):
+        OpenAIGenerator(api_key="sk-test")
+
+
+def test_client_construction_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+    module = types.ModuleType("openai")
+
+    def failing_factory(*, api_key: str | None = None) -> None:
+        raise RuntimeError("client init failed")
+
+    module.OpenAI = failing_factory
+    monkeypatch.setitem(sys.modules, "openai", module)
+
+    with pytest.raises(GeneratorError, match="Could not initialize OpenAI client") as exc_info:
+        OpenAIGenerator(api_key="sk-test")
+
+    assert isinstance(exc_info.value.__cause__, RuntimeError)
+
+
+def test_api_failure(fake_openai: list[FakeOpenAIClient]) -> None:
+    generator, client = _make_generator(fake_openai)
+    client.chat.completions.create_side_effect = RuntimeError("API unavailable")
+
+    with pytest.raises(GeneratorError, match="OpenAI generation failed") as exc_info:
+        generator.generate("Question?", [Chunk(id="1", content="context")])
+
+    assert isinstance(exc_info.value.__cause__, RuntimeError)
+
+
+def test_empty_response_raises_generator_error(
+    fake_openai: list[FakeOpenAIClient],
+) -> None:
+    generator, client = _make_generator(fake_openai)
+    client.chat.completions.response_content = ""
+
+    with pytest.raises(GeneratorError, match="empty response"):
+        generator.generate("Question?", [])
+
+
+def test_constructor_configuration(fake_openai: list[FakeOpenAIClient]) -> None:
+    generator = OpenAIGenerator(
+        model="custom-model",
+        api_key="sk-test",
+        system_prompt="Custom prompt.",
+        max_tokens=512,
+    )
+
+    assert generator.model == "custom-model"
+    assert generator.system_prompt == "Custom prompt."
+    assert generator.max_tokens == 512
diff --git a/tests/test_pipeline/test_async_rag.py b/tests/test_pipeline/test_async_rag.py
new file mode 100644
index 0000000..ea1cff0
--- /dev/null
+++ b/tests/test_pipeline/test_async_rag.py
@@ -0,0 +1,58 @@
+
+"""Tests for AsyncRAGPipeline."""
+
+import pytest
+
+from ragframework.config import RAGConfig
+from ragframework.document.chunkers import FixedSizeChunker
+from ragframework.document.loaders import TextFileLoader
+from ragframework.embeddings.random_embedder import RandomEmbedder
+from ragframework.generator.echo_generator import EchoGenerator
+from ragframework.pipeline.async_rag import AsyncRAGPipeline
+from ragframework.pipeline.rag import RAGPipeline
+from ragframework.retriever.in_memory import InMemoryRetriever
+
+
+@pytest.fixture()
+def pipeline(tmp_text_file):
+    return RAGPipeline(
+        loader=TextFileLoader(),
+        chunker=FixedSizeChunker(chunk_size=50, chunk_overlap=10),
+        embedder=RandomEmbedder(dim=16, seed=0),
+        retriever=InMemoryRetriever(),
+        generator=EchoGenerator(),
+        config=RAGConfig(top_k=2),
+    )
+
+
+@pytest.mark.asyncio
+async def test_async_ingest(pipeline, tmp_text_file):
+    async_pipeline = AsyncRAGPipeline.from_pipeline(pipeline)
+
+    count = await async_pipeline.async_ingest(tmp_text_file)
+
+    assert count > 0
+
+
+@pytest.mark.asyncio
+async def test_async_query(pipeline, tmp_text_file):
+    async_pipeline = AsyncRAGPipeline.from_pipeline(pipeline)
+
+    await async_pipeline.async_ingest(tmp_text_file)
+    response = await async_pipeline.async_query("What is this about?")
+
+    assert response.answer
+    assert isinstance(response.source_chunks, list)
+
+
+def test_config_is_forwarded(pipeline):
+    async_pipeline = AsyncRAGPipeline.from_pipeline(pipeline)
+
+    assert async_pipeline.config.top_k == 2
+
+
+def test_from_pipeline_wraps_existing_pipeline(pipeline):
+    async_pipeline = AsyncRAGPipeline.from_pipeline(pipeline)
+
+    assert async_pipeline._pipeline is pipeline
+
diff --git a/tests/test_pipeline/test_rag.py b/tests/test_pipeline/test_rag.py
index 98f18a0..a20cc3d 100644
--- a/tests/test_pipeline/test_rag.py
+++ b/tests/test_pipeline/test_rag.py
@@ -2,6 +2,7 @@
 
 import pytest
 
+from ragframework.base import Chunk, Embedder, Generator, Reranker
 from ragframework.config import RAGConfig
 from ragframework.document.chunkers import FixedSizeChunker
 from ragframework.document.loaders import TextFileLoader
@@ -12,6 +13,28 @@
 from ragframework.retriever.in_memory import InMemoryRetriever
 
 
+class ReverseReranker(Reranker):
+    def rerank(self, query, chunks, top_k):
+        return list(reversed(chunks))[:top_k]
+
+
+class RecordingGenerator(Generator):
+    def __init__(self):
+        self.context = []
+
+    def generate(self, query, context):
+        self.context = list(context)
+        return "ok"
+
+
+class MixedDimensionEmbedder(Embedder):
+    def embed(self, texts):
+        embeddings = [[0.0] * 8 for _ in texts]
+        if len(embeddings) > 1:
+            embeddings[1] = [0.0] * 3
+        return embeddings
+
+
 @pytest.fixture()
 def pipeline(tmp_text_file):
     return RAGPipeline(
@@ -40,6 +63,46 @@ def test_query_top_k_respected(self, pipeline, tmp_text_file):
         response = pipeline.query("test")
         assert len(response.source_chunks) <= 2
 
+    def test_query_with_reranker(self):
+        class FixedRetriever(InMemoryRetriever):
+            def retrieve(self, query_embedding, top_k=5):
+                return [Chunk(id="1", content="one"), Chunk(id="2", content="two")][:top_k]
+
+        p = RAGPipeline(
+            loader=TextFileLoader(),
+            chunker=FixedSizeChunker(),
+            embedder=RandomEmbedder(dim=16, seed=0),
+            retriever=FixedRetriever(),
+            generator=EchoGenerator(),
+            reranker=ReverseReranker(),
+            config=RAGConfig(top_k=1, retrieve_k=2),
+        )
+        assert p.query("test").source_chunks[0].id == "2"
+
+    def test_query_without_reranker_limits_final_context_to_top_k(self):
+        class FixedRetriever(InMemoryRetriever):
+            def retrieve(self, query_embedding, top_k=5):
+                return [
+                    Chunk(id=str(i), content=f"chunk {i}")
+                    for i in range(top_k)
+                ]
+
+        generator = RecordingGenerator()
+        p = RAGPipeline(
+            loader=TextFileLoader(),
+            chunker=FixedSizeChunker(),
+            embedder=RandomEmbedder(dim=16, seed=0),
+            retriever=FixedRetriever(),
+            generator=generator,
+            config=RAGConfig(top_k=2, retrieve_k=8),
+        )
+
+        response = p.query("test")
+
+        assert [chunk.id for chunk in generator.context] == ["0", "1"]
+        assert [chunk.id for chunk in response.source_chunks] == ["0", "1"]
+
+
     def test_ingest_missing_file_raises_pipeline_error(self, pipeline):
         with pytest.raises(PipelineError):
             pipeline.ingest("/no/such/file.txt")
@@ -64,3 +127,89 @@ def test_default_config_used_when_none_given(self):
             generator=EchoGenerator(),
         )
         assert p.config.top_k == 5
+
+    def test_embedding_dimension_mismatch_during_ingest(self, tmp_text_file):
+        p = RAGPipeline(
+            loader=TextFileLoader(),
+            chunker=FixedSizeChunker(),
+            embedder=RandomEmbedder(dim=16),
+            retriever=InMemoryRetriever(),
+            generator=EchoGenerator(),
+            config=RAGConfig(embedding_dim=8),
+        )
+
+        with pytest.raises(
+            PipelineError,
+            match=r"Embedder produced 16-dim vectors but RAGConfig\.embedding_dim is 8",
+        ):
+            p.ingest(tmp_text_file)
+
+    def test_ingest_validates_every_embedding_before_indexing(self, tmp_text_file):
+        retriever = InMemoryRetriever()
+        p = RAGPipeline(
+            loader=TextFileLoader(),
+            chunker=FixedSizeChunker(chunk_size=20, chunk_overlap=0),
+            embedder=MixedDimensionEmbedder(),
+            retriever=retriever,
+            generator=EchoGenerator(),
+            config=RAGConfig(embedding_dim=8),
+        )
+
+        with pytest.raises(
+            PipelineError,
+            match=r"Embedder produced 3-dim vectors but RAGConfig\.embedding_dim is 8",
+        ):
+            p.ingest(tmp_text_file)
+
+        assert len(retriever) == 0
+
+    def test_embedding_dimension_mismatch_during_query(self):
+        p = RAGPipeline(
+            loader=TextFileLoader(),
+            chunker=FixedSizeChunker(),
+            embedder=RandomEmbedder(dim=16),
+            retriever=InMemoryRetriever(),
+            generator=EchoGenerator(),
+            config=RAGConfig(embedding_dim=8),
+        )
+
+        with pytest.raises(
+            PipelineError,
+            match=r"Embedder produced 16-dim vectors but RAGConfig\.embedding_dim is 8",
+        ):
+            p.query("test")
+
+    def test_embedding_dimension_none_disables_validation(self, pipeline, tmp_text_file):
+        assert pipeline.config.embedding_dim is None
+        assert pipeline.ingest(tmp_text_file) > 0
+
+    def test_from_config_builds_chunker(self):
+        config = RAGConfig(chunk_size=37, chunk_overlap=9, embedding_dim=16)
+
+        p = RAGPipeline.from_config(
+            config,
+            loader=TextFileLoader(),
+            embedder=RandomEmbedder(dim=16),
+            retriever=InMemoryRetriever(),
+            generator=EchoGenerator(),
+        )
+
+        assert isinstance(p.chunker, FixedSizeChunker)
+        assert p.chunker.chunk_size == 37
+        assert p.chunker.chunk_overlap == 9
+        assert p.config is config
+
+    def test_from_config_preserves_reranker(self):
+        config = RAGConfig(embedding_dim=16)
+        reranker = ReverseReranker()
+
+        p = RAGPipeline.from_config(
+            config,
+            loader=TextFileLoader(),
+            embedder=RandomEmbedder(dim=16),
+            retriever=InMemoryRetriever(),
+            generator=EchoGenerator(),
+            reranker=reranker,
+        )
+
+        assert p.reranker is reranker
diff --git a/tests/test_reranker/test_cross_encoder.py b/tests/test_reranker/test_cross_encoder.py
new file mode 100644
index 0000000..276c45a
--- /dev/null
+++ b/tests/test_reranker/test_cross_encoder.py
@@ -0,0 +1,47 @@
+"""Tests for rerankers."""
+
+import sys
+import types
+
+from ragframework.base import Chunk
+from ragframework.reranker import CrossEncoderReranker, NoOpReranker
+
+
+class FakeCrossEncoder:
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def predict(self, pairs):
+        return [0.1, 0.9]
+
+
+def test_cross_encoder_reranks(monkeypatch):
+    module = types.ModuleType("sentence_transformers")
+    module.CrossEncoder = FakeCrossEncoder
+    monkeypatch.setitem(sys.modules, "sentence_transformers", module)
+
+    chunks = [Chunk(id="a", content="a"), Chunk(id="b", content="b")]
+    result = CrossEncoderReranker().rerank("q", chunks, 1)
+
+    assert result[0].id == "b"
+    assert result[0].metadata["rerank_score"] == 0.9
+
+
+def test_cross_encoder_skips_prediction_for_empty_candidates(monkeypatch):
+    class FailOnPredictCrossEncoder:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        def predict(self, pairs):
+            raise AssertionError("predict should not be called for empty candidates")
+
+    module = types.ModuleType("sentence_transformers")
+    module.CrossEncoder = FailOnPredictCrossEncoder
+    monkeypatch.setitem(sys.modules, "sentence_transformers", module)
+
+    assert CrossEncoderReranker().rerank("q", [], 1) == []
+
+
+def test_noop_reranker():
+    chunks = [Chunk(id="a", content="a"), Chunk(id="b", content="b")]
+    assert NoOpReranker().rerank("q", chunks, 1) == chunks[:1]
diff --git a/tests/test_retriever/test_chroma.py b/tests/test_retriever/test_chroma.py
index 22497c8..1b00dd2 100644
--- a/tests/test_retriever/test_chroma.py
+++ b/tests/test_retriever/test_chroma.py
@@ -142,15 +142,21 @@ def test_non_positive_top_k_returns_empty():
         ]
     )
 
-    assert retriever.retrieve(
-        [1.0, 0.0],
-        top_k=0,
-    ) == []
+    assert (
+        retriever.retrieve(
+            [1.0, 0.0],
+            top_k=0,
+        )
+        == []
+    )
 
-    assert retriever.retrieve(
-        [1.0, 0.0],
-        top_k=-1,
-    ) == []
+    assert (
+        retriever.retrieve(
+            [1.0, 0.0],
+            top_k=-1,
+        )
+        == []
+    )
 
 
 def test_metadata_is_preserved():
diff --git a/tests/test_retriever/test_in_memory.py b/tests/test_retriever/test_in_memory.py
index b0aaea7..7f948e3 100644
--- a/tests/test_retriever/test_in_memory.py
+++ b/tests/test_retriever/test_in_memory.py
@@ -36,7 +36,6 @@ def test_chunk_without_embedding_raises(self):
             r.add([bad_chunk])
 
     def test_retrieve_returns_most_similar_first(self):
-        dim = 4
         r = InMemoryRetriever()
         # chunk_a is identical to the query — highest similarity
         chunk_a = make_chunk("a", [1.0, 0.0, 0.0, 0.0])
@@ -45,3 +44,95 @@ def test_retrieve_returns_most_similar_first(self):
         r.add([chunk_a, chunk_b, chunk_c])
         results = r.retrieve([1.0, 0.0, 0.0, 0.0], top_k=3)
         assert results[0].id == "a"
+
+    @pytest.mark.parametrize("populated", [False, True])
+    def test_empty_batch_is_a_no_op(self, populated):
+        r = InMemoryRetriever()
+        existing = make_chunk("existing", [1.0, 0.0])
+        if populated:
+            r.add([existing])
+
+        r.add([])
+
+        assert len(r) == int(populated)
+        assert r.retrieve([1.0, 0.0]) == ([existing] if populated else [])
+
+    @pytest.mark.parametrize("populated", [False, True])
+    @pytest.mark.parametrize(
+        ("embedding", "message"),
+        [
+            (None, "no embedding"),
+            ([], "non-empty one-dimensional"),
+            ([[1.0, 0.0]], "non-empty one-dimensional"),
+            (["not-a-number", 0.0], "numeric"),
+            ([float("nan"), 0.0], "finite"),
+            ([float("inf"), 0.0], "finite"),
+            ([0.0, 0.0], "zero vector"),
+        ],
+    )
+    def test_invalid_batch_leaves_retriever_usable(self, populated, embedding, message):
+        r = InMemoryRetriever()
+        existing = make_chunk("existing", [1.0, 0.0])
+        if populated:
+            r.add([existing])
+
+        with pytest.raises(RetrieverError, match=message):
+            r.add([make_chunk("good", [0.0, 1.0]), make_chunk("bad", embedding)])
+
+        assert len(r) == int(populated)
+        assert r.retrieve([1.0, 0.0]) == ([existing] if populated else [])
+        # A failed first batch must not establish the index dimension.
+        recovered = make_chunk("recovered", [0.0, 2.0] if populated else [0.0, 2.0, 0.0])
+        r.add([recovered])
+        assert r.retrieve(recovered.embedding, top_k=1) == [recovered]
+
+    def test_inconsistent_first_batch_does_not_establish_dimension(self):
+        r = InMemoryRetriever()
+        with pytest.raises(
+            RetrieverError, match="Chunk 'three' embedding has dimension 3; expected 2"
+        ):
+            r.add([make_chunk("two", [1.0, 0.0]), make_chunk("three", [1.0, 0.0, 0.0])])
+
+        assert len(r) == 0
+        assert r.retrieve([1.0, 0.0]) == []
+        recovered = make_chunk("recovered", [1.0, 0.0, 0.0])
+        r.add([recovered])
+        assert r.retrieve([1.0, 0.0, 0.0]) == [recovered]
+
+    def test_wrong_dimension_append_preserves_existing_results(self):
+        r = InMemoryRetriever()
+        north = make_chunk("north", [10.0, 0.0])
+        east = make_chunk("east", [0.0, 3.0])
+        r.add([east, north])
+        with pytest.raises(
+            RetrieverError, match="Chunk 'bad' embedding has dimension 3; expected 2"
+        ):
+            r.add([make_chunk("good", [1.0, 1.0]), make_chunk("bad", [1.0, 0.0, 0.0])])
+
+        assert len(r) == 2
+        assert r.retrieve([2.0, 0.0]) == [north, east]
+        northeast = make_chunk("northeast", [1.0, 1.0])
+        r.add([northeast])
+        assert len(r) == 3
+        assert r.retrieve([2.0, 0.0]) == [north, northeast, east]
+
+    @pytest.mark.parametrize(
+        ("embedding", "message"),
+        [
+            ([], "non-empty one-dimensional"),
+            ([[1.0, 0.0]], "non-empty one-dimensional"),
+            (["not-a-number", 0.0], "numeric"),
+            ([float("nan"), 0.0], "finite"),
+            ([float("inf"), 0.0], "finite"),
+            ([0.0, 0.0], "zero vector"),
+            ([1.0, 0.0, 0.0], "has dimension 3; expected 2"),
+        ],
+    )
+    def test_invalid_query_raises_retriever_error(self, embedding, message):
+        r = InMemoryRetriever()
+        existing = make_chunk("existing", [1.0, 0.0])
+        r.add([existing])
+        with pytest.raises(RetrieverError, match=f"Query embedding .*{message}"):
+            r.retrieve(embedding)
+
+        assert r.retrieve([1.0, 0.0]) == [existing]