src/ — The Library

🎯 Why This Module Exists

The src/ tree is a deliberate exercise in API archaeology — copying LangChain.js's class shape (Document, BaseLoader.load(), BaseTextSplitter.splitText(), Embeddings.embedQuery(), BaseLLM.invoke/stream) but stripping every abstraction the educational arc doesn't yet need. A reader who graduates from this codebase can open LangChain's docs and recognise every primitive.

The current src/ is deliberately partial: only the layers the first six lessons depend on are filled in (embeddings/, text-splitters/, loaders/, llms/, utils/). The empty chains/, retrievers/, vector-stores/, and prompts/ are scaffolded with named-export index.js files — they hold a place in the import graph for future lessons. Without this module, every example would duplicate ~50 lines of Document, splitter base, and cache plumbing; the curriculum would lose its sense of progression.

🏗️ Design Decisions

Architecture

classDiagram
    class Document {
      +pageContent: string
      +metadata: object
      +id?: string
      +toJSON()
      +fromJSON()
    }
    class BaseLoader {
      <<abstract>>
      +load() Document[]
      +loadAndSplit(splitter)
      +loadLazy()
    }
    class PDFLoader {
      +source: string|Buffer
      +splitPages: boolean
      +load()
    }
    class BaseTextSplitter {
      +chunkSize: number
      +chunkOverlap: number
      +lengthFunction(t)
      +splitText()*
      +splitDocuments(docs)
      +mergeSplits(splits, sep)
    }
    class CharacterTextSplitter {
      +separator: string
    }
    class RecursiveCharacterTextSplitter {
      +separators: string[]
      +splitText(text)
    }
    class TokenTextSplitter {
      +encodingName: string
    }
    class EmbeddingModel {
      +modelPath: string
      +dimensions: 384
      +cache: EmbeddingCache
      +initialize()
      +embedQuery(text)
      +embedDocuments(texts)
      +similarity(a, b)
    }
    class EmbeddingCache {
      +maxSize: 10000
      +get(text)
      +set(text, vec)
      +saveToDisk()
      +_evictLRU()
    }
    class BaseLLM {
      <<abstract>>
      +invoke(prompt)*
      +stream(prompt)*
      +batch(prompts)
    }
    class LlamaCpp {
      +static initialize(inputs)
      +invoke(prompt, opts)
      +stream(prompt, opts)
      +dispose()
    }
    class ChatLlamaCpp {
      +invoke(messages)
      +_formatMessagesToPrompt(msgs)
    }
    BaseLoader <|-- PDFLoader
    BaseTextSplitter <|-- CharacterTextSplitter
    BaseTextSplitter <|-- RecursiveCharacterTextSplitter
    BaseTextSplitter <|-- TokenTextSplitter
    BaseLLM <|-- LlamaCpp
    LlamaCpp <|-- ChatLlamaCpp
    EmbeddingModel *-- EmbeddingCache
    PDFLoader ..> Document : emits
    BaseTextSplitter ..> Document : emits
    EmbeddingModel ..> Document : reads

Data Flow

sequenceDiagram
    participant U as User code
    participant L as PDFLoader
    participant S as RecursiveCharSplitter
    participant E as EmbeddingModel
    participant C as EmbeddingCache
    participant Lc as node-llama-cpp
    U->>L: new PDFLoader(url).load()
    L->>L: pdf-parse + cleanText
    L-->>U: Document[]
    U->>S: splitDocuments(docs)
    S->>S: choose separator from priority list
    S->>S: mergeSplits with overlap
    S-->>U: Document[] chunked
    U->>E: embedDocuments(texts)
    loop batch of 32
        E->>C: get(text) [SHA-256 key]
        alt hit
            C-->>E: vector
        else miss
            E->>Lc: ctx.getEmbeddingFor(text)
            Lc-->>E: Float32Array[384]
            E->>C: set(text, vector)
        end
    end
    E-->>U: number[][]
    Note over U,Lc: User now stores vectors in their
preferred vector DB. src/vector-stores/
is the future home for wrappers.

Key Components

⚡ Algorithm Spotlight

Three algorithms drive the substantive sub-modules:

Deep-Dive Highlights

Core sub-modules extracted into dedicated pages.

⚠ What Could Go Wrong

📊 Performance Profile

Fast paths. Cache hits in EmbeddingModel.embedQuery are O(1) Map lookup plus a SHA-256 (~5µs for short text). Batch embedding parallelises within a batch via Promise.all — wall-clock is bound by the slowest item, not the sum. Splitter mergeSplits is a single O(N) pass over the input.

Slow paths. Cold model load (LlamaCpp.initialize) is ~1–3 s for a 1B-parameter quantised model on a CPU laptop. Embedding fresh text routes through llama.cpp's getEmbeddingFor() — ~10–50 ms per call depending on model size and CPU. Chunked PDFs of typical academic-paper length (10–30 pages) take ~5–15 s end-to-end on the first run, sub-second on subsequent runs (cache).

Memory. EmbeddingCache is bounded by maxSize (default 10,000). At 384 dims × 4 bytes = ~1.5 KB per entry → ~15 MB at full capacity. Disk dumps write JSON (verbose but trivially loadable). Tradeoff: no Protobuf / no MessagePack — sticking to JSON keeps the cache human-inspectable, which is what an educational repo wants.

Directory Map

src/
├── index.js                              ← Re-exports every sub-module
├── embeddings/
│   ├── EmbeddingModel.js   (320 LOC)    ← LangChain-shaped wrapper
│   ├── EmbeddingCache.js   (425 LOC)    ← LRU + JSON persistence
│   └── index.js
├── text-splitters/
│   ├── BaseTextSplitter.js          (99 LOC)
│   ├── CharacterTextSplitter.js     (18 LOC)
│   ├── RecursiveCharacterTextSplitter.js (59 LOC)
│   ├── TokenTextSplitter.js         (23 LOC)
│   └── index.js
├── loaders/
│   ├── BaseLoader.js                (43 LOC)
│   ├── PDFLoader.js                (160 LOC)   ← only concrete loader
│   ├── DirectoryLoader.js              (stub)
│   ├── TextLoader.js                   (stub)
│   └── index.js
├── llms/
│   ├── BaseLLM.js                   (43 LOC)
│   ├── LlamaCpp.js                 (106 LOC)
│   └── index.js
├── chat-models/
│   └── ChatLlamaCpp.js              (32 LOC)
├── utils/
│   ├── Document.js                  (55 LOC)   ← universal payload
│   ├── llama_cpp.js                 (69 LOC)   ← factory functions
│   ├── similarity.js                   (stub)
│   ├── tokenizer.js                    (stub)
│   ├── validators.js                   (stub)
│   └── index.js
├── chains/   retrievers/   vector-stores/   prompts/
│   └── index.js + class .js stubs           ← future homes
└── README.md

Configuration Reference

Code Examples

Embed a query and a document

import { EmbeddingModel } from './src/embeddings/EmbeddingModel.js';

const embeddings = new EmbeddingModel({
    modelPath: './models/bge-small-en-v1.5.Q8_0.gguf',
    cache: true,
    batchSize: 32
});
await embeddings.initialize();

const queryVec = await embeddings.embedQuery('What is RAG?');
const docVecs  = await embeddings.embedDocuments([
    'Retrieval-Augmented Generation combines retrieval with LLMs.',
    'The capital of France is Paris.'
]);

const sim = await embeddings.similarity('RAG explained', 'Retrieval-Augmented Generation');
console.log('similarity:', sim);  // ~0.85

Split a PDF into overlapping chunks

import { PDFLoader, RecursiveCharacterTextSplitter } from './src/index.js';

const loader = new PDFLoader('https://arxiv.org/pdf/2005.11401', { splitPages: true });
const pages = await loader.load();   // Document[]; one per page

const splitter = new RecursiveCharacterTextSplitter({
    chunkSize: 1000,
    chunkOverlap: 200,
    separators: ['\n\n', '\n', '. ', ' ', '']
});
const chunks = await splitter.splitDocuments(pages);
console.log(`${pages.length} pages -> ${chunks.length} chunks`);

Local LLM completion with grammar-constrained output

import { LlamaCpp } from './src/llms/LlamaCpp.js';

const llm = await LlamaCpp.initialize({
    modelPath: './models/Qwen3-1.7B.Q8_0.gguf',
    contextSize: 2048,
    temperature: 0.2,
    maxTokens: 256,
    // Optional: constrain output to JSON via GBNF
    gbnf: 'root ::= "{" ws "\"answer\":" ws string ws "}"'
});

const response = await llm.invoke('What is RAG?');
console.log(response);
await llm.dispose();

Sub-Module Cards