Bulletproof RAG: Production Curriculum

Module 01: Introduction

Module 02: Naive RAG

Module 03: Data Engineering

Module 04: Query Intelligence

Module 05: Advanced Retrieval

Module 06: Agentic Architectures

Module 07: Evaluation

RAG Logging and Observability

Technical Stack Configuration

Step-by-step setup for a reliable RAG development environment using Node.js and the Vercel AI SDK v6.

A successful RAG implementation depends on a stable, decoupled development environment. This guide configures the unified installation process for PDF extraction, semantic vectorization, and grounded inference. By standardizing our base utilities, we ensure that every module in this curriculum remains consistent and testable.

Engineering Trade-offs

Feature	Technical Impact
Pros	Centralized dependency management; standardized logging across the pipeline; reduces repetitive bootstrap code.
Cons	Initial setup time for key management; mandatory environment configuration for model access.

Architecture Overview

The setup phase prepares the runtime environment for the following data flow:

       [.env]
          │
          ▼
   ┌───────────────┐
   │ Node.js Env   │ (Loading Model API Keys)
   └───────┬───────┘
           │
   ┌───────▼───────┐
   │ AI SDK config │ (Embedding & LLM model providers)
   └───────┬───────┘
           │
   ┌───────▼───────┐
   │ Test Data path│ (Standardizing file system access)
   └───────────────┘

Implementation Walkthrough

The following steps define the baseline environment for the "Bulletproof RAG" stack.

Production Dependency Installation

Standardize on the Vercel AI SDK v6.0. This unified interface prevents vendor lock-in and provides type-safety across multiple model providers. We also include tsx for running TypeScript scripts directly.

npm install ai @ai-sdk/openai unpdf @langchain/textsplitters dotenv zod
npm install -D tsx @types/node

Global Environment Configuration

Define your API keys in a .env file at the project root. This separation of code and secrets is non-negotiable for RAG pipelines.

OPENAI_API_KEY=sk_your_production_key_here

Complete Production Script

This utility script verifies document access and SDK connectivity before we move to vector search.

import fs from 'fs/promises';
import path from 'path';
import 'dotenv/config';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
 
/**
 * Baseline Configuration Test script.
 * Verifies key loading and file system permissions.
 */
async function bootstrap() {
  const logger = {
    info: (msg: string) => console.log(`[INFO]  ${new Date().toISOString()} | ${msg}`),
    error: (msg: string) => console.error(`[FATAL] ${new Date().toISOString()} | ${msg}`)
  };
 
  try {
    logger.info("Initializing environment probe...");
    
    // Check API Key
    if (!process.env.OPENAI_API_KEY) {
      throw new Error("Missing OPENAI_API_KEY in environment.");
    }
    
    // Check Data Path Permissions
    const dataDir = path.resolve('./data');
    const testFilePath = path.join(dataDir, 'AI_Information.pdf');
    
    try {
      await fs.mkdir(dataDir, { recursive: true });
      logger.info(`Ensuring data directory exists at: ${dataDir}`);
    } catch (e) {
      // Ignore if exists
    }
 
    try {
      await fs.access(testFilePath);
      logger.info(`Test file detected at: ${testFilePath}`);
    } catch (e) {
      logger.info(`[WARN] Test data missing: Please ensure ${testFilePath} exists for subsequent modules.`);
    }
 
    // Verify SDK Connectivity
    logger.info("Verifying SDK connectivity...");
    const { text } = await generateText({
      model: openai('gpt-4o-mini'),
      prompt: 'Check if environment is RAG-ready. Reply with "RAG Ready" if you can hear me.',
    });
    
    logger.info(`Verification result: ${text.trim()}`);
    console.log(`\n--- SETUP COMPLETE: ENVIRONMENT READY ---\n`);
 
  } catch (error: any) {
    logger.error(error.message);
    process.exit(1);
  }
}
 
bootstrap();

Summary of Impact

Metric	Improper Setup	Standard Setup
Debugging Time	High (Key errors, missing files)	Low (Early environment validation)
Pipeline Stability	Low (Runtime crashes)	High (Pre-flight checks)
Portability	Low (Hardcoded paths)	High (Relative path logic)

When to Use This

At the start of any new RAG project.
To troubleshoot API connectivity issues in a CI/CD environment.
When onboarding team members to the standardized RAG stack.

Next PageThe Naive RAG Implementation

On This Page

Engineering Trade-offs Architecture Overview Implementation Walkthrough Complete Production Script Summary of Impact When to Use This

Connect with the Author

Have questions or suggestions? Feel free to reach out.

Feature

Technical Impact

Pros

Centralized dependency management; standardized logging across the pipeline; reduces repetitive bootstrap code.

Cons

Initial setup time for key management; mandatory environment configuration for model access.

Architecture Overview

The setup phase prepares the runtime environment for the following data flow:

       [.env]
          │
          ▼
   ┌───────────────┐
   │ Node.js Env   │ (Loading Model API Keys)
   └───────┬───────┘
           │
   ┌───────▼───────┐
   │ AI SDK config │ (Embedding & LLM model providers)
   └───────┬───────┘
           │
   ┌───────▼───────┐
   │ Test Data path│ (Standardizing file system access)
   └───────────────┘

Implementation Walkthrough

The following steps define the baseline environment for the "Bulletproof RAG" stack.

Production Dependency Installation

npm install ai @ai-sdk/openai unpdf @langchain/textsplitters dotenv zod
npm install -D tsx @types/node

Global Environment Configuration

Define your API keys in a .env file at the project root. This separation of code and secrets is non-negotiable for RAG pipelines.

OPENAI_API_KEY=sk_your_production_key_here

Complete Production Script

This utility script verifies document access and SDK connectivity before we move to vector search.

import fs from 'fs/promises';
import path from 'path';
import 'dotenv/config';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
 
/**
 * Baseline Configuration Test script.
 * Verifies key loading and file system permissions.
 */
async function bootstrap() {
  const logger = {
    info: (msg: string) => console.log(`[INFO]  ${new Date().toISOString()} | ${msg}`),
    error: (msg: string) => console.error(`[FATAL] ${new Date().toISOString()} | ${msg}`)
  };
 
  try {
    logger.info("Initializing environment probe...");
    
    // Check API Key
    if (!process.env.OPENAI_API_KEY) {
      throw new Error("Missing OPENAI_API_KEY in environment.");
    }
    
    // Check Data Path Permissions
    const dataDir = path.resolve('./data');
    const testFilePath = path.join(dataDir, 'AI_Information.pdf');
    
    try {
      await fs.mkdir(dataDir, { recursive: true });
      logger.info(`Ensuring data directory exists at: ${dataDir}`);
    } catch (e) {
      // Ignore if exists
    }
 
    try {
      await fs.access(testFilePath);
      logger.info(`Test file detected at: ${testFilePath}`);
    } catch (e) {
      logger.info(`[WARN] Test data missing: Please ensure ${testFilePath} exists for subsequent modules.`);
    }
 
    // Verify SDK Connectivity
    logger.info("Verifying SDK connectivity...");
    const { text } = await generateText({
      model: openai('gpt-4o-mini'),
      prompt: 'Check if environment is RAG-ready. Reply with "RAG Ready" if you can hear me.',
    });
    
    logger.info(`Verification result: ${text.trim()}`);
    console.log(`\n--- SETUP COMPLETE: ENVIRONMENT READY ---\n`);
 
  } catch (error: any) {
    logger.error(error.message);
    process.exit(1);
  }
}
 
bootstrap();

Metric

Improper Setup

Standard Setup

Debugging Time

High (Key errors, missing files)

Low (Early environment validation)

Pipeline Stability

Low (Runtime crashes)

High (Pre-flight checks)

Portability

Low (Hardcoded paths)

High (Relative path logic)

Technical Stack Configuration

Engineering Trade-offs

Architecture Overview

Implementation Walkthrough

Global Environment Configuration
Define your API keys in a `.env` file at the project root. This separation of code and secrets is non-negotiable for RAG pipelines.
`OPENAI_API_KEY=sk_your_production_key_here`

Complete Production Script

Summary of Impact

When to Use This

Technical Stack Configuration

Engineering Trade-offs

Architecture Overview

Implementation Walkthrough

Global Environment Configuration
Define your API keys in a `.env` file at the project root. This separation of code and secrets is non-negotiable for RAG pipelines.
`OPENAI_API_KEY=sk_your_production_key_here`

Complete Production Script

Summary of Impact

When to Use This

Technical Stack Configuration

Engineering Trade-offs

Architecture Overview

Implementation Walkthrough

Global Environment ConfigurationDefine your API keys in a .env file at the project root. This separation of code and secrets is non-negotiable for RAG pipelines..env ConfigurationVerificationCopyOPENAI_API_KEY=sk_your_production_key_here

Complete Production Script

Summary of Impact

When to Use This

Technical Stack Configuration

Engineering Trade-offs

Architecture Overview

Implementation Walkthrough

Global Environment ConfigurationDefine your API keys in a .env file at the project root. This separation of code and secrets is non-negotiable for RAG pipelines..env ConfigurationVerificationCopyOPENAI_API_KEY=sk_your_production_key_here

Complete Production Script

Summary of Impact

When to Use This

Global Environment Configuration
Define your API keys in a `.env` file at the project root. This separation of code and secrets is non-negotiable for RAG pipelines.
`OPENAI_API_KEY=sk_your_production_key_here`

Global Environment Configuration
Define your API keys in a `.env` file at the project root. This separation of code and secrets is non-negotiable for RAG pipelines.
`OPENAI_API_KEY=sk_your_production_key_here`