|
| 1 | +# Changelog |
| 2 | + |
| 3 | +All notable changes to **rag-cpp** are documented here. The format follows |
| 4 | +[Keep a Changelog](https://keepachangelog.com/), and the project aims to follow |
| 5 | +[Semantic Versioning](https://semver.org/). |
| 6 | + |
| 7 | +## [0.1.0] — 2025-07-26 |
| 8 | + |
| 9 | +The first tagged release. rag-cpp is a type-theoretic, production-grade retrieval |
| 10 | +(RAG) engine in modern C++23: one library, no vector-DB dependency, with a |
| 11 | +conformant RCP/1 protocol server and a C ABI. CI is green on macOS (clang, with |
| 12 | +and without Metal) and Linux (gcc); the RCP server is certified **conformance |
| 13 | +level L2**. |
| 14 | + |
| 15 | +> Versioned `0.1.0` — the library is stable and measured, but the C++ API is not |
| 16 | +> yet frozen at 1.0. The **C ABI** (`rag/c/rag.h`) is already versioned at 1.0 |
| 17 | +> and evolves compatibly. The on-disk `.ragdb` format is versioned and |
| 18 | +> CRC-checked (see `FORMAT.md`). |
| 19 | +
|
| 20 | +### Retrieval core |
| 21 | + |
| 22 | +- **Hybrid retrieval** — BM25 (inverted index) and dense (vector) retrievers run |
| 23 | + concurrently so hybrid latency is `max`, not the sum. |
| 24 | +- **Score fusion** — `convex` (default), `rrf`, and `rsf`; the convex default was |
| 25 | + measured at +18% nDCG@10 over RRF on the eval harness. |
| 26 | +- **HNSW ANN** with filtered search, tunable `ef` as a per-query dial, and |
| 27 | + measured recall/QPS curves on real datasets (GloVe, SIFT). |
| 28 | +- **Quantization** — SQ8-quantized graph walk with full-precision rescoring |
| 29 | + (3.2× smaller at 0.93 recall) and optional PQ for very large corpora. |
| 30 | +- **Metadata filtering** evaluated during the walk, not as a post-filter. |
| 31 | + |
| 32 | +### Advanced retrieval |
| 33 | + |
| 34 | +- **SPLADE** (learned sparse), **ColBERT** (late-interaction MaxSim), |
| 35 | + **RAPTOR** (hierarchical summary tree), **HyDE** and multi-query rewriting, |
| 36 | + **Corrective RAG (CRAG)**, a budgeted **cascade**, and **GraphRAG** |
| 37 | + (`graph_local` / `graph_global`). |
| 38 | +- **Contextual Retrieval** (Anthropic 2024) as an ingest transform, reachable via |
| 39 | + `CorpusConfig::contextual` and `ragcpp index --contextual`. |
| 40 | + |
| 41 | +### Pipeline |
| 42 | + |
| 43 | +- Composable `RetrievalStage`s with three pre-assembled factories: |
| 44 | + `Pipeline::standard()` (the default), `Pipeline::quality()` (+MMR diversity), |
| 45 | + and `Pipeline::context()` (+ParentStitch small-to-big). The two extras are |
| 46 | + opt-in and carry measured justifications. |
| 47 | + |
| 48 | +### Embedders & plugins |
| 49 | + |
| 50 | +- Backends: `hash`, `ollama`, `openai`, `voyage`, `together`, `llamacpp`, plus |
| 51 | + in-process `onnx` and `gguf`. |
| 52 | +- **Composition from config** — `retry` and `fallback` decorators resolve nested |
| 53 | + specs, so resilience is declarative and `fallback` degrades even when a primary |
| 54 | + can't be constructed. |
| 55 | +- **Plugin registry** — register a backend by name; a one-function authoring API |
| 56 | + (`register_embedder` / `Config` / `resolve`) makes adding one trivial. Ship a |
| 57 | + backend as a shared library and load it at runtime with no host recompile. |
| 58 | +- **Polyglot bridge** — drive an engine / retriever / graph written in any |
| 59 | + language over a process or HTTP channel. |
| 60 | +- `ragcpp list` prints every registered backend with its config keys. |
| 61 | + |
| 62 | +### Performance |
| 63 | + |
| 64 | +Measured, not assumed: parallel HNSW build, allocation-free search, overlapped |
| 65 | +retrievers, memoized Porter stemmer (3.1× faster ingest), precomputed BM25 |
| 66 | +postings, and a **Metal GPU** batch-scoring backend (6–9× on large batches where |
| 67 | +it wins, never slower otherwise). |
| 68 | + |
| 69 | +### Durability & serving |
| 70 | + |
| 71 | +- **Write-ahead log** — an acknowledged write is `O(record)`, not `O(corpus)` |
| 72 | + (25 ms → 1.35 ms at 20k docs); opening the WAL performs crash recovery. |
| 73 | +- Stable, versioned, CRC-checked **`.ragdb`** container; reopening never rebuilds. |
| 74 | +- **RCP/1 server** (stdio + HTTP) consuming the pinned RCP C++ SDK; certified |
| 75 | + conformance **L2**. Crash-safe writes, per-request pipeline overrides, and |
| 76 | + exact citations (`startLine`/`endLine`) for grounded generation. |
| 77 | + |
| 78 | +### C ABI & bindings |
| 79 | + |
| 80 | +- Flat opaque-handle C API (`rag/c/rag.h`, version 1.0) drives the whole engine |
| 81 | + from Python/Rust/Go; errors cross as status codes, never exceptions. |
| 82 | + |
| 83 | +### Tooling & quality |
| 84 | + |
| 85 | +- **CI** across macOS (clang ± Metal), Linux (gcc), a `-Werror` job, and a |
| 86 | + pinned-SDK "clean clone" job that verifies the build a stranger gets. |
| 87 | +- Comprehensive docs in [`docs/`](docs/), plus `ARCHITECTURE.md`, `PLUGINS.md`, |
| 88 | + and `FORMAT.md`. |
| 89 | + |
| 90 | +[0.1.0]: https://github.com/1ay1/rag-cpp/releases/tag/v0.1.0 |
0 commit comments