Skip to content

Commit cfe46ce

Browse files
committed
Add CHANGELOG for the 0.1.0 release
Summarize the first tagged release by capability area (retrieval core, advanced retrieval, pipeline, embedders/plugins, performance, durability/serving, C ABI, tooling) rather than commit-by-commit. Note the versioning contract: 0.1.0 signals a stable-but-not-API-frozen library, while the C ABI is already 1.0 and the .ragdb format is versioned + CRC-checked. Linked from the README.
1 parent 75053cf commit cfe46ce

2 files changed

Lines changed: 91 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
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

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -270,6 +270,7 @@ Full guides live in [**`docs/`**](docs/README.md). Start there if you're new.
270270

271271
**Reference**
272272

273+
- [`CHANGELOG.md`](CHANGELOG.md) — release notes.
273274
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — layers, seams, invariants.
274275
- [`PLUGINS.md`](PLUGINS.md) — the three extension axes: concepts, `AnyX`, and the
275276
load-time plugin registry (register backends by name / from a shared library).

0 commit comments

Comments
 (0)