@demystify/rag

TypeScript client for the dmstfy-rag API — grounded RAG queries with citations, groundedness scores, honest abstention and SSE streaming.

import { createRagClient } from "@demystify/rag";

const rag = createRagClient({ baseUrl, key, product: "supportedge" });
await rag.ingest("kb", { docKey: "refund-policy", content: markdown });

const r = await rag.query("kb", "What's the refund window for annual plans?");
if (r.abstained) showGapMessage(r.clarifying_question);
else render(r.answer, r.citations); // inline [1][2] markers map to r.citations

for await (const event of rag.queryStream("kb", "…")) {
  if (event.type === "delta") process.stdout.write(event.content);
}

Run the service

This package is a client — it needs a running dmstfy-rag service to talk to. Prebuilt service images are published to GHCR (ghcr.io/demystify-systems/dmstfy-rag-api). The fastest start is the demo profile: one container, in-memory store, mock gateway, deterministic heuristic AI ports — fully offline, no API keys, no database:

# docker-compose.yml — minimal offline demo
services:
  rag:
    image: ghcr.io/demystify-systems/dmstfy-rag-api:0.2 # match your client's 0.x minor
    ports:
      - "8084:8084"
    environment:
      DMSTFY_PROFILE: demo # in-memory store + mock gateway + heuristic AI profile

then point the client at it:

const rag = createRagClient({
  baseUrl: "http://localhost:8084",
  tenantId: "00000000-0000-4000-8000-000000000001", // demo auth trusts the tenant header
});

For the production shapes (Postgres/pgvector, real gateway-backed embeddings and generation, key auth), see the image reference: service images and the module README.

Is there an embeddable / local mode?

Honest answer: the RAG engine is not published as a standalone npm library today — @demystify/rag is the HTTP client only. The service image in DMSTFY_PROFILE=demo is the local mode: in-memory adapters, zero infrastructure, zero keys, deterministic outputs — one docker run away. An embeddable engine package (run the query machine in-process, no HTTP hop) is under consideration for 0.4.

Errors

Errors are thrown as RagApiError with status, code (branch on this), type and requestId. Full API + framing: modules/dmstfy-rag/openapi/rag-api.yaml in the demystify monorepo.

Versioning & compatibility

Pre-1.0 semver: a 0.x minor may contain breaking changes, a patch never does — pin ~0.x.y. The client requires a rag service on the same 0.x minor; servers reject unknown request fields with invalid_request, and the deprecated x-tenant-id header alias (DEPRECATED_HEADER_ALIASES.tenant, exported here) is accepted through 0.3.x with removal targeted at 0.4.0. Full policy: versioning-policy.md. Changes: CHANGELOG.md.