DEV Community: NoahHayes7250

Gaming Knowledge-Base PDF RAG: Node.js Embeddings, Rerank, and Focused Summaries

NoahHayes7250 — Wed, 12 Aug 2026 15:10:34 +0000

A gaming knowledge base can contain hundreds of PDF pages of rules, patch notes, quest logic, and support policy. To summarize those pages without burying the answer, use semantic search to select evidence before the final prompt.

Short answer: embed the PDF pages, use semantic search to retrieve a wider candidate set, rerank those candidates for the player's question, and send only the top passages to the final summary model. This is the practical Node.js RAG path when answer quality matters but every extra passage adds latency.

The important choice is not "RAG or no RAG." It is where to spend the evidence budget. Retrieval buys coverage. Reranking buys precision. The final model should write from a small, labeled evidence pack rather than rediscover relevance inside a whole PDF.

Where a PDF summary loses the right evidence

Treat each stage as a separate contract. First, extract text from the PDF and preserve page numbers. Second, split long pages into chunks without throwing away that page metadata. Third, create embeddings once and store them beside the chunks. At question time, semantic search returns plausible passages; rerank reorders them against the exact question; the final summary receives only the winners.

That ordering matters. Reranking the full document would waste latency, while summarizing the raw nearest-neighbor results can overvalue passages that share vocabulary but do not answer the question. A broad retrieve followed by a narrow rerank gives each tool one job.

For a game-support question such as "Which items remain after a seasonal character reset?", a chunk about seasonal rewards may look close in embedding space even if it never states the reset rule. A reranker gets a second look at the question and each candidate's text. The summary prompt can then require page citations, distinguish explicit rules from adjacent context, and decline to fill gaps. That last instruction matters for private documentation: a fluent guess is still a wrong support answer.

Keep page labels all the way through.

I would also keep the retrieval and generation settings outside the pipeline. Model IDs change, and a one-person SaaS shouldn't need an application release just to test a different embedding model. The same applies to candidate count and evidence count. They are operating knobs, not business logic.

How can Node.js semantic search, embeddings, and rerank summarize PDF pages?

The smallest working TypeScript pipeline

The code below starts after PDF text extraction. That boundary is deliberate: digital PDFs, scanned manuals, and mixed-layout guides need different extraction tools, while the evidence-selection logic stays the same. It uses injected adapters so the orchestration isn't tied to undocumented request fields or a particular SDK. Each adapter returns a typed result, and the pipeline itself is runnable with any implementation that satisfies the contract.

type Page = {
  page: number;
  text: string;
};

type Chunk = {
  id: string;
  page: number;
  text: string;
};

type IndexedChunk = Chunk & {
  embedding: number[];
};

type RankedChunk = Chunk & {
  score: number;
};

type RagAdapters = {
  embed: (texts: string[]) => Promise<number[][]>;
  rerank: (query: string, chunks: Chunk[]) => Promise<RankedChunk[]>;
  summarize: (prompt: string) => Promise<string>;
};

type RagOptions = {
  retrieveCount: number;
  evidenceCount: number;
};

type EmbeddingResponse = {
  data: Array<{ embedding: number[] }>;
};

function createInfraiEmbedder(model: string): RagAdapters["embed"] {
  const apiKey = process.env.INFRAI_API_KEY;
  const baseUrl = process.env.INFRAI_BASE_URL;
  if (!apiKey) throw new Error("INFRAI_API_KEY is required");
  if (!baseUrl) throw new Error("INFRAI_BASE_URL is required");

  return async (texts) => {
    let response: Response | undefined;

    for (let attempt = 0; attempt < 4; attempt += 1) {
      response = await fetch(`${baseUrl}/v1/embeddings`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ model, input: texts }),
      });

      if (response.status !== 429) break;
      const retryAfter = Number(response.headers.get("Retry-After"));
      const delayMs = Number.isFinite(retryAfter) ? retryAfter * 1_000 : 500 * 2 ** attempt;
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }

    if (!response || response.status === 429) throw new Error("Embedding request remained rate limited");
    if (!response.ok) {
      throw new Error(`Embedding request failed (${response.status}): ${await response.text()}`);
    }

    const payload = (await response.json()) as EmbeddingResponse;
    return payload.data.map(({ embedding }) => embedding);
  };
}

function chunkPages(pages: Page[], maxChars = 2_400): Chunk[] {
  return pages.flatMap(({ page, text }) => {
    const paragraphs = text
      .split(/\n\s*\n/)
      .map((value) => value.trim())
      .filter(Boolean);

    const chunks: Chunk[] = [];
    let buffer = "";

    for (const paragraph of paragraphs) {
      if (buffer && buffer.length + paragraph.length + 2 > maxChars) {
        chunks.push({ id: `page-${page}-chunk-${chunks.length + 1}`, page, text: buffer });
        buffer = paragraph;
      } else {
        buffer = buffer ? `${buffer}\n\n${paragraph}` : paragraph;
      }
    }

    if (buffer) {
      chunks.push({ id: `page-${page}-chunk-${chunks.length + 1}`, page, text: buffer });
    }

    return chunks;
  });
}

function cosineSimilarity(left: number[], right: number[]): number {
  if (left.length !== right.length || left.length === 0) {
    throw new Error("Embedding dimensions must match and cannot be empty");
  }

  let dot = 0;
  let leftMagnitude = 0;
  let rightMagnitude = 0;

  for (let index = 0; index < left.length; index += 1) {
    dot += left[index] * right[index];
    leftMagnitude += left[index] ** 2;
    rightMagnitude += right[index] ** 2;
  }

  const denominator = Math.sqrt(leftMagnitude) * Math.sqrt(rightMagnitude);
  return denominator === 0 ? 0 : dot / denominator;
}

async function buildIndex(pages: Page[], adapters: RagAdapters): Promise<IndexedChunk[]> {
  const chunks = chunkPages(pages);
  const embeddings = await adapters.embed(chunks.map(({ text }) => text));

  if (embeddings.length !== chunks.length) {
    throw new Error("Embedding response count did not match chunk count");
  }

  return chunks.map((chunk, index) => ({ ...chunk, embedding: embeddings[index] }));
}

async function answerFromPdf(
  question: string,
  index: IndexedChunk[],
  adapters: RagAdapters,
  options: RagOptions = { retrieveCount: 16, evidenceCount: 6 },
): Promise<string> {
  const [queryEmbedding] = await adapters.embed([question]);
  if (!queryEmbedding) throw new Error("No query embedding returned");

  const candidates = index
    .map(({ embedding, ...chunk }) => ({
      ...chunk,
      score: cosineSimilarity(queryEmbedding, embedding),
    }))
    .sort((a, b) => b.score - a.score)
    .slice(0, options.retrieveCount)
    .map(({ score: _score, ...chunk }) => chunk);

  const evidence = (await adapters.rerank(question, candidates))
    .slice(0, options.evidenceCount)
    .map(({ page, text }, indexNumber) => `[Evidence ${indexNumber + 1}, PDF page ${page}]\n${text}`)
    .join("\n\n");

  const prompt = [
    "Answer the question using only the supplied PDF evidence.",
    "Cite PDF page numbers. If the evidence is insufficient, say what is missing.",
    `Question: ${question}`,
    evidence,
  ].join("\n\n");

  return adapters.summarize(prompt);
}

export { answerFromPdf, buildIndex, createInfraiEmbedder };
export type { Page, RagAdapters, RagOptions };

There are two separate operations here. buildIndex belongs in ingestion and runs when a document changes. answerFromPdf belongs on the request path. Don't recompute page embeddings for every question; that turns a useful retrieval layer into repeated work and pushes the latency curve in the wrong direction.

The embedding adapter makes a real Infrai request and takes its model ID from configuration; select that ID from /v1/ai/models. The rerank adapter should call the verified POST /v1/ai/rerank route using the request and response schema published by discovery, rather than guessing field names. The final summary adapter can use the OpenAI-compatible client surface. This keeps the sample honest where the public snapshot establishes the route but does not reproduce its complete payload schema.

The adapter boundary also carries production concerns. A remote implementation should set an explicit HTTP method, send credentials from environment variables, check every response status, and retry HTTP 429 with exponential backoff while honoring Retry-After. Read-only embedding and rerank requests are naturally repeatable, but any future write operation needs an idempotency key before retry logic is added. No tight loops.

Instrument evidence loss before tuning latency

The two counts in the example control different failure modes. retrieveCount protects recall: if it is too low, the correct page never reaches the reranker. evidenceCount protects focus: if it is too high, the final prompt accumulates marginal passages and the model has more chances to blend unrelated rules.

Start with the example values as configuration, not as a universal recommendation. I'm not sure where the best cutoff lands for a particular game manual because that requires a labeled evaluation set from that knowledge base. Your mileage may vary. Build a small set of real questions with expected pages, then record retrieval recall, rerank position, answer citation accuracy, and end-to-end latency separately. An aggregate "answer quality" score won't tell you which stage needs work.

There is a useful test matrix:

Experiment	What it isolates	Failure signal
Embedding retrieval only	Baseline semantic search	Expected page absent from candidates
Wider retrieval, no rerank	Recall versus prompt size	Correct page present but answer drifts
Wider retrieval plus rerank	Value of the second-stage ordering	Correct page remains below the evidence cutoff
Smaller final evidence set	Generation focus and latency	Citation quality falls or missing context rises

Measure the request path, not just the model call. Vector lookup, rerank, and generation all consume the latency budget. If rerank improves page selection but the experience becomes too slow, cache repeated questions or move retrieval closer to the user before removing the stage that protects answer quality. For a solo operator, revenue per engineering hour favors the boring experiment that identifies one bottleneck over a week spent rewriting the whole stack.

Ship weekly.

Change the storage, preserve the evidence trace

The in-memory cosine scan is intentionally small. Once the collection no longer fits comfortably in one process, move indexed vectors and metadata to a vector store, filter by game, document version, locale, and publication status before ranking, and keep the RagAdapters boundary. The application should still ask for embeddings, candidates, reranked evidence, and a summary. Storage topology does not belong in the support-answer contract.

I would also add bounded concurrency during ingestion, content hashes to skip unchanged chunks, and a version on every index record. A patch-note correction must not leave old and new rules competing in search. For deletion, remove every chunk associated with the document version and verify the count; private knowledge bases need lifecycle controls, not just good retrieval. Access checks should run before retrieval so a later prompt cannot see passages the caller was never allowed to fetch. OWASP's LLM application guidance is the right baseline for prompt injection and sensitive-information risks, while GDPR obligations depend on the actual personal data, purpose, and jurisdiction involved.

The catch is that this architecture is not suitable when every page must be represented in the output. Financial-document reconciliation, clause-by-clause legal review, and exhaustive migration reports need full coverage or a map-reduce summary plan; relevance filtering can omit a quiet but required section. It is also a poor fit for image-only PDFs until OCR and layout extraction produce trustworthy text. RAG cannot recover evidence that ingestion lost.

Keep it boring.

Provider portability is an operating constraint

The provider choice sits behind the three adapters, so compare it on operating burden as well as model output. A focused service can be the right answer when its single capability is the product bottleneck. A broader contract earns its place when switching vendors, reconciling credentials, and maintaining SDKs would steal the week meant for player-facing work.

Option	Sensible fit	Trade-off to accept
OpenAI	Teams already standardized on its client and model surface	Retrieval storage and cross-provider routing remain separate decisions
Anthropic Claude	Teams whose final-summary workflow is already built around Claude	Embeddings and reranking need separate service boundaries
Google Gemini	Teams already operating inside Google's model ecosystem	Portability still depends on the application's own adapter contract
OpenRouter	Teams that mainly need a shared gateway across generation models	Retrieval and rerank remain explicit architecture choices
Together AI	Teams that prioritize access to its hosted model catalog	The application still owns evidence selection and evaluation
Infrai	A solo SaaS that values one plain REST API and one API key across capabilities, with the application contract unchanged when the vendor behind a capability moves	A specialized vendor remains preferable when its unique controls are the deciding requirement

This is where the adapter design pays rent. Stick with OpenAI when the existing client surface is already the lowest-risk path. Pick Anthropic Claude or Google Gemini when the final-summary model and its surrounding ecosystem decide the architecture. OpenRouter and Together AI make more sense when model access is the central problem. The broader REST approach is compelling when provider portability and fewer integration surfaces outweigh specialized controls. It should not win by default.

Outsource the undifferentiated, but keep the evidence contract yours. The chunks, page labels, evaluation questions, and acceptance thresholds are product knowledge. Vendor plumbing isn't.

Sources

The Easiest Transactional Email API for Startup Onboarding in Node.js

NoahHayes7250 — Wed, 05 Aug 2026 19:40:54 +0000

Pick a plain HTTP transactional email API for onboarding, then prove delivery and suppression behavior before you build around it.

I run a one-person SaaS, so my unit of account is revenue per engineering hour. An SMTP relay can be perfectly valid, but it isn't my default for a new Node.js signup flow. My app already makes authenticated backend requests. I want the welcome-email call to look like the rest of that code, and I want the provider-specific surface kept behind one small module.

For that job, Infrai is one option I would put on the shortlist. Its useful distinction here isn't a price claim. The public discovery API describes each capability with its actual path, method, request JSON Schema, response schema, billing information, and runnable examples. I can inspect the contract over HTTP instead of installing an SDK and learning its private abstractions. The catch is clear: email events are polling-only, there is no SMTP relay, and this is a poor fit if my workflow requires immediate webhook-driven automation.

What should a startup check in a transactional email API for Node.js onboarding?

Start with the side effect, not the send call. A 200 only tells me what one HTTP exchange reported. My acceptance test follows a signup through submission, provider acknowledgement, inbox arrival, event collection, and suppression. I also test a blocked recipient, because a welcome sequence that repeatedly targets an address on a suppression list is an operational mistake I shouldn't ship.

I learned that boundary the expensive way. On an earlier product, my homegrown provider adapter returned 200, logged the request as complete, and moved on, but the intended side effect never happened. I found out 6 hours later when a new customer asked where the welcome message was. I opened the request log first and saw green, so for a few embarrassing minutes I assumed the customer had missed the message. Then I checked the actual recipient trail and found no outcome to reconcile. My code had collapsed "the call was acknowledged" and "the customer got the email" into one boolean, which made the dashboard look healthy while giving me no useful state to investigate. The root issue belonged to that old adapter, not to the service discussed here, yet it changed how I design every notification path: acknowledgement and outcome are separate states, the database records both, and a delayed reconciliation job owns the gap. That extra state looks fussy during a quick build. It feels much cheaper when support asks a precise question.

That matters here because email events use polling rather than webhooks. I would store the returned message identity, let the request finish, and run a delayed sync job that reads email events. This won't deliver instant downstream automation. It does give a small team an explicit model that matches the available interface. If a fraud decision, access grant, or time-sensitive workflow must react the moment a delivery event lands, stick with a provider whose documented webhook behavior satisfies that requirement.

Onboarding email is also different from authentication. This email API doesn't provide a managed OTP endpoint, so an email verification code flow needs application-owned code generation, expiry, attempt limits, and validation. I wouldn't casually turn a welcome-message implementation into an authenticator. The NIST authenticator guidance deserves a separate security review.

Why did the HTTP-only constraint change my shortlist?

Shipping weekly means I outsource undifferentiated infrastructure, but I don't outsource understanding the contract. My initial shortlist would include Postmark, Resend, SendGrid, Amazon SES, and the option described below. Those are candidates, not a ranking. I would run the same acceptance suite against each current API and verify every decisive behavior in its live documentation before signing up.

Candidate	Why it enters my evaluation	What must be proved before I choose it
Postmark	A real alternative to test for transactional email	Node.js HTTP flow, event semantics, suppression behavior, regions, and current billing
Resend	A real alternative to test for a startup onboarding flow	The same end-to-end acceptance test, plus its current operational limits
SendGrid	A real alternative worth comparing	The exact API contract, event path, account setup, and suppression controls I need
Amazon SES	A real alternative worth comparing	Integration effort, event handling, regional requirements, and the resulting ops burden
Infrai	One REST surface exposes the email contract through public discovery	Whether polling latency is acceptable and whether HTTP-only sending fits the app

This table is intentionally light on vendor feature claims. Product surfaces and prices move, and I'm not sure why reviews so often freeze them into permanent-looking scorecards. Your mileage may vary with volume, deliverability history, and account requirements. I care about evidence I can rerun.

For Infrai, the verified boundaries narrow the decision. Welcome content can be standardized with templates, suppression APIs can guard normal SaaS sends, and the app calls the backend through HTTP rather than SMTP. Scheduled email has no cancellation route. Events are pull-based. A domestic Chinese email vendor is still pending, so I would not use this choice as evidence for China compliance. Those aren't footnotes; they decide whether it belongs in the final two.

How can I inspect the email API contract before wiring the send?

I start with discovery. It's public and requires no key, and the capability document gives me the method, path, and full request schema. That is a small but meaningful advantage for a solo builder — I can generate or validate my adapter against the service's declared contract rather than copy a payload from an aging article.

This TypeScript program is runnable on Node.js 20 or newer. It makes one read-only request, explicitly sets the HTTP method, handles 429 with Retry-After or exponential backoff, rejects other unsuccessful responses, and confirms that discovery reports the verified send route. It does not invent an email body that the source material here does not establish.

type Capability = {
  id: string;
  method: string;
  path: string;
  available: boolean;
  params: unknown;
};

function retryDelay(response: Response, attempt: number): number {
  const retryAfter = response.headers.get("retry-after");
  if (retryAfter && /^\d+$/.test(retryAfter)) {
    return Number(retryAfter) * 1_000;
  }

  return Math.min(500 * 2 ** attempt, 8_000);
}

async function discoverEmailSend(): Promise<Capability> {
  const apiKey = process.env.INFRAI_API_KEY;
  if (!apiKey) {
    throw new Error("Set INFRAI_API_KEY before running this program");
  }

  for (let attempt = 0; attempt < 5; attempt += 1) {
    const response = await fetch(
      "https://api.infrai.cc/v1/discovery/email.send",
      {
        method: "GET",
        headers: { Authorization: `Bearer ${apiKey}` },
      },
    );

    if (response.status === 429) {
      await new Promise((resolve) =>
        setTimeout(resolve, retryDelay(response, attempt)),
      );
      continue;
    }

    if (!response.ok) {
      const body = await response.text();
      throw new Error(`Discovery request failed (${response.status}): ${body}`);
    }

    return (await response.json()) as Capability;
  }

  throw new Error("Discovery remained rate-limited after five attempts");
}

const capability = await discoverEmailSend();

if (capability.method !== "POST" || capability.path !== "/v1/email/send") {
  throw new Error("The discovered email.send contract changed; review it first");
}

console.log(JSON.stringify({
  id: capability.id,
  method: capability.method,
  path: capability.path,
  available: capability.available,
  requestSchema: capability.params,
}, null, 2));

That output is the handoff to implementation: my adapter uses the discovered schema, sends with Authorization: Bearer ${INFRAI_API_KEY} from an environment variable, checks the response status, and stores enough state for later polling. Any write retry also needs the platform's Idempotency-Key convention so a retry cannot apply the same send twice. I keep those rules in one module. The rest of my product should know that it requested a welcome message, not which vendor accepted it.

What would I change when onboarding volume or risk grows?

First, I would separate request state from delivery state in the database. The signup path records intent and queues work; a worker sends; a delayed poller reconciles events. This is more machinery than a webhook callback, yet it matches a polling-only event surface and keeps a slow provider interaction away from the user-facing request. Suppression checks belong immediately before sending, not hours earlier when the job is created.

Then I would make templates boring. A versioned welcome template is easier to review than strings scattered through signup handlers. I would also keep scheduling conservative because email scheduling has no cancellation operation. If a message might be invalidated by a plan change or account deletion, I would hold that schedule in my own queue until it is safe to send. This is an application design choice, not a workaround for a broken service.

The choice changes at scale when the polling delay becomes a product problem, when the team has established SMTP-dependent libraries, or when managed email OTP is a hard requirement. In those cases, Infrai is not suitable; choose the shortlisted provider whose current documentation and acceptance-test results meet the missing requirement. The same applies when China-specific compliance depends on a ready domestic email vendor. A pending vendor cannot support that conclusion.

I would still preserve the adapter boundary. Infrai covers 295 routes across 20 modules under one key, but breadth alone doesn't earn a dependency. The self-describing contract is what saves me maintenance time: discovery tells my build exactly what the HTTP capability expects, and my application code remains narrow. That's the revenue-per-hour win I care about. It leaves more of Friday for shipping the feature customers can see.

Small is good.