fix(rag): make the RAG docs' own examples compile, and load the chatbot config by borisno2 · Pull Request #1318 · OpenSaasAU/stack

borisno2 · 2026-09-07T19:09:31Z

Fixes the QA round-three defects on #1128 (N5, N6, N7). Both blocking items are the same shape — guidance that contradicts the code it documents — so each was fixed by class and the whole file swept, not just the line QA named.

N5 (blocking) — `chunkText`'s documented call did not compile

packages/rag/CLAUDE.md:57 had its signature corrected last round; the file's own usage example 439 lines below did not. It passed maxTokens/overlap, which are the field-level ChunkingConfig member names, not chunkText's ChunkingOptions, and fed the returned TextChunk[] straight to embedBatch(string[]).

Fixed there and at examples/rag-ollama-demo/README.md:452. Sweep result: every other chunkText call site in the repo (rag-advanced.md ×5, reference/rag.md ×3, packages/rag/README.md ×3) already used the correct names — those two were the only survivors.

The sweep found one more of the same class that QA did not report. Compiling every documented call of every RAG export in packages/rag/CLAUDE.md turned up the registerEmbeddingProvider example reading config.model and config.dimensions straight off the EmbeddingProviderConfig union, whose custom member is an open { type: string; [key: string]: unknown }:

TS2345: Type 'unknown' is not assignable to type 'string'.   (model)
TS2339: Property 'dimensions' does not exist on type 'EmbeddingProviderConfig'.

The example now narrows both, and the prose says why. The identical defect in docs/content/how-to/rag-advanced.md:123 is fixed the same way.

Every other documented RAG export call — semanticSearch, findSimilar, generateEmbedding, batchProcess, searchable, embedding, ragPlugin, the StoredEmbedding literal — checks out against source; nothing else changed.

N6 (blocking) — the chatbot example's config could not load

examples/rag-openai-chatbot/opensaas.config.ts imported PrismaPg from @prisma/adapter-pg, not a dependency of that example, and declared prismaClientConstructor, not a member of DatabaseConfig. PR #1263 converted the sibling config in the same commit and left this one behind, so story 16's "both RAG examples reseed" was unexecutable — an incomplete sweep within this PRD, not a spec-9 deferral.

Fixed exactly as c0d443fb fixed the sibling: adapter import and constructor removed, db: { provider: 'postgresql' } kept. That is also the shape #1315 had already written into this example's README, so file and README now agree.

How it was confirmed. Reproduced the failure first, with the sibling as control:

FAILED: ./opensaas.config.ts
  Cannot find package '@prisma/adapter-pg' imported from …/rag-openai-chatbot/opensaas.config.ts
CONFIG LOADED: ../rag-ollama-demo/opensaas.config.ts     (control)

After the fix it loads, with ragPlugin declaring the pgvector pack exactly as the sibling does:

CONFIG LOADED: …/rag-openai-chatbot/opensaas.config.ts
  db: {"provider":"postgresql","extensions":[{"name":"pgvector","from":"@prisma/orm-extension-pgvector"}]}
  lists: KnowledgeBase

Pushed further than "loads": opensaas generate now runs end to end on this example, seeding the pgvector space and emitting pg/vector@1 at length: 1536 — the 1536-dimension analogue of the vector(768) #1263 verified for the sibling. The generated artifacts are not committed: both examples share an identically stale prisma.config.ts, so regenerating only this one would have made the siblings diverge over a pre-existing shared condition rather than #1263's leftover.

Left alone as genuinely spec 9's (#1129): the other examples importing @prisma/adapter-better-sqlite3. pg/@types/pg stay declared — #1263 pruned no dependencies from the sibling.

N7 (low) — broken path

packages/rag/README.md pointed at examples/rag-demo, which does not exist, and credited it with MCP integration and multiple providers — neither of which either real example has (verified: no mcp block and a single provider in both configs). It now names examples/rag-ollama-demo and examples/rag-openai-chatbot and says what each actually demonstrates.

Sweep result: every other path and anchor in the RAG surface resolves (./CLAUDE.md, #provisioning-pgvector, generation-failure.ts, packages/cli/src/commands/{db,dev}.ts). One further stale claim turned up and is fixed: docs/content/reference/rag.md:711 still described the ollama demo as using "SQLite VSS", which #1263 removed from the example itself. Sweeping the whole RAG surface for sqlite/vss leaves only legitimate test assertions that a sqlite datasource is refused, and for prismaClientConstructor/adapter imports, zero survivors.

Verification

Every code sample was extracted verbatim to a scratch project outside the repo, with @opensaas/* mapped to the built type declarations, and compiled. Harness falsified first: the uncorrected snippet reproduces QA's exact TS2353 + TS2345 there, while the corrected control compiles clean — so the diagnostics belong to the snippets, not the probe. Final formatted text of every changed block recompiles at exit 0.

Gates: pnpm lint 0 errors (2 pre-existing warnings) · pnpm build 11/11 including the docs build · rag 448 passed / 2 skipped (20 files) · cli 406 passed (42 files) — all matching QA's recorded baselines. pnpm manypkg fix and pnpm format clean. Changeset included (minor, @opensaas/stack-rag).

Not addressed, correctly out of scope: #1316, #1317, and the tracked set including #1265, #1271, #1272, #1310, #1311.

🤖 Generated with Claude Code

…ot config QA round three on #1128. Both blocking items are the same shape: guidance that contradicts the code it documents, fixed by class rather than by line number. `chunkText`'s export-list entry was corrected last round; its usage example 439 lines below was not. It passed `maxTokens`/`overlap` — the field-level `ChunkingConfig` names, not `ChunkingOptions` — and fed the returned `TextChunk[]` straight to `embedBatch(string[])`. Corrected here and at `examples/rag-ollama-demo/README.md:452`, the only other survivor. Sweeping every documented call of every RAG export in that file against the real signatures turned up one more of the same class, unreported: the `registerEmbeddingProvider` example read `config.model` and `config.dimensions` off the `EmbeddingProviderConfig` union, whose custom member is an open `{ type: string; [key: string]: unknown }`. So `model` arrives as `unknown` and `dimensions` is not on the union at all — two type errors. The example now narrows both and the prose says why. The identical defect in `docs/content/how-to/rag-advanced.md` is fixed the same way. `examples/rag-openai-chatbot/opensaas.config.ts` could not be loaded at all: it imported `PrismaPg` from `@prisma/adapter-pg`, which is not a dependency of that example, and declared `prismaClientConstructor`, which is not a member of `DatabaseConfig`. #1263 converted the sibling config in the same commit and left this one behind, so story 16's "both RAG examples reseed" was unexecutable. Fixed exactly as c0d443f fixed the sibling — adapter import and constructor removed, `db: { provider: 'postgresql' }` kept — which is also the shape #1315 had already written into this example's README. The package README pointed at `examples/rag-demo`, which does not exist, and credited it with MCP integration and multiple providers, which neither real example has. It now names both real examples and what each actually does. Verified: every code sample extracted verbatim to a scratch project mapped at the built declarations compiles at exit 0, with the harness falsified first — the uncorrected snippet reproduces TS2353 and TS2345 there. The chatbot config loads (`db: postgresql` with ragPlugin's pgvector pack declared), with the ollama sibling as control, and `opensaas generate` now runs it end to end, emitting `pg/vector@1` at `length: 1536`. Gates: lint 0 errors (2 pre-existing warnings), build 11/11 including docs, rag 448 passed / 2 skipped, cli 406 passed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

chatgpt-codex-connector · 2026-09-07T19:09:35Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

vercel · 2026-09-07T19:09:37Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
stack-docs	Ready	Preview	Sep 7, 2026 9:27pm UTC

changeset-bot · 2026-09-07T19:09:38Z

🦋 Changeset detected

Latest commit: 136f2b2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@opensaas/stack-rag	Minor
@opensaas/stack-cli	Minor
@opensaas/stack-auth	Minor
@opensaas/stack-core	Minor
@opensaas/stack-storage-s3	Minor
@opensaas/stack-storage-vercel	Minor
@opensaas/stack-storage	Minor
@opensaas/stack-tiptap	Minor
@opensaas/stack-ui	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-09-07T19:20:01Z