Retrieval ingest/search endpoints (one ingest door, /api/retrieval/*)
Generated from
pattern-library/registry.json— do not edit by hand; change the registry and runbun run patterns:build.
Category: AI · Tier: deep · Maturity: proven (verified 2026-08-20 @ 1a130d67) · Risk: medium — writes to the corpus store; provider quotas apply
The RAG corpus is fed and queried through /api/retrieval/* HTTP endpoints plus a unified ingest door: the app runtime and the Bun docs-ingest script share the same pure planChunks() core.
When to use: Use when the corpus must be maintainable from more than one runtime (app UI and scripts) without forking chunking logic.
Requires: postgres, pgvector, ai-provider
Avoid when
- The corpus is fed from one runtime only — a single in-process ingest call needs no HTTP door or shared pure chunker
- Chunking needs I/O such as per-chunk LLM contextual prep — the door is shareable across runtimes only because planChunks() is pure
Alternatives
- Ingest in-process from the app alone, with no script or HTTP door — prefer when documents arrive only through the app UI and are never bulk-loaded by a script
Docs
- docs/blueprint/ai/knowledge-base.md — The ingest door pattern (GitHub · GitLab)
Code
src/routes/api/retrieval/ingest/+server.ts— Ingest endpoint (namespace is /api/retrieval/, not /api/rag/) (GitHub · GitLab)src/routes/api/retrieval/search/+server.ts— Search endpoint (GitHub · GitLab)src/lib/server/retrieval/ingest/index.ts— Runtime ingest module (GitHub · GitLab)scripts/db/ingest-docs.ts— Bun script sharing the same planChunks() door (GitHub · GitLab)
Tests
Proof
/showcases/ai/chatbot— Retrieval now lives as the #retrieval section of the surface pages; the ingest/explorer showcases were retired
Invariants
- One ingest door: the standalone script reuses the app's pure planChunks() so both runtimes share one chunking implementation.
- Section-parent chunks are stored with embedding = NULL so tier-1 retrieval never surfaces them.
- Re-ingest is resume-safe and idempotent.
Emulation notes
- Keep the chunker pure (no I/O) — that is what makes the door shareable across runtimes.
- Mind embedding-provider daily quotas when re-ingesting a whole corpus.
Depends on
Machine-readable record: retrieval-endpoints in pattern-library/registry.json.