@forgedevstack/forge-ai

Thin RAG toolkit for TypeScript: text chunking, provider-agnostic embeddings, pgvector SQL helpers, and document extraction types. Zero runtime dependencies — the embedding client uses the global fetch.

Part of the ForgeStack ecosystem.

Install

npm install @forgedevstack/forge-ai

Quick Example

Chunk a document, embed the chunks, and store/query them with pgvector:

import {
  chunkText,
  createOpenAiEmbeddingProvider,
  buildCreateTableSql,
  buildSimilarityQuerySql,
  formatVectorLiteral,
} from '@forgedevstack/forge-ai';

const chunks = chunkText(documentText, {
  strategy: 'sentence',
  chunkSize: 512,
  overlap: 64,
});

const provider = createOpenAiEmbeddingProvider({
  baseUrl: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY ?? '',
});

const embeddings = await provider.embed(chunks.map((chunk) => chunk.text));

await db.query(buildCreateTableSql({ table: 'documents', dimensions: provider.dimensions }));

for (const [position, chunk] of chunks.entries()) {
  await db.query(
    'INSERT INTO documents (content, embedding) VALUES ($1, $2)',
    [chunk.text, formatVectorLiteral(embeddings[position])],
  );
}

const [queryEmbedding] = await provider.embed(['What is ForgeStack?']);
const results = await db.query(
  buildSimilarityQuerySql({ table: 'documents', topK: 5 }),
  [formatVectorLiteral(queryEmbedding)],
);

The similarity query uses a $1 placeholder for the query vector — pass the output of formatVectorLiteral as the query parameter.

API Overview

Chunking

• chunkText(text, options?) — dispatches on options.strategy ('fixed' default, or 'sentence').
• chunkFixedSize(text, options?) — sliding character window of chunkSize stepping chunkSize - overlap, with correct startOffset/endOffset on every chunk.
• chunkBySentence(text, options?) — splits on sentence boundaries (., !, ? followed by whitespace), packs sentences up to chunkSize characters, and carries trailing sentences up to overlap characters into the next chunk.

Both throw when overlap >= chunkSize. Defaults: chunkSize 512, overlap 64.

Embeddings

• createOpenAiEmbeddingProvider(options) — returns an EmbeddingProvider targeting any OpenAI-compatible embeddings endpoint (POST {baseUrl}/embeddings). Supports custom model, dimensions, headers, and fetchImpl for testing or non-global fetch. Results are sorted by response index. Non-ok responses throw with status and body.
• Implement the EmbeddingProvider interface to plug in any other provider.

pgvector

• buildCreateTableSql(options) — CREATE EXTENSION IF NOT EXISTS vector; plus a CREATE TABLE IF NOT EXISTS statement with id (bigserial), text, vector(dimensions), and JSONB metadata columns. Column names are configurable.
• buildSimilarityQuerySql(options) — cosine distance (<=>) query with configurable select columns, optional WHERE clause, and LIMIT topK (default 5).
• formatVectorLiteral(embedding) — formats a number[] as a pgvector literal like [0.1,0.2,0.3].

Document Extraction

• Extractor, ExtractorInput, ExtractedDocument, and SupportedDocumentFormat ('pdf' | 'docx' | 'xlsx') types describe the extraction contract.
• createExtractorRegistry(initial?) — registry with register, get, and has; get throws for unregistered formats.
• createStubExtractor(format) — placeholder whose extract rejects, naming the optional peer dependency to install.

pdf-parse, mammoth, and xlsx are optional peer dependencies. v0.1.0 ships only the Extractor interface and stubs — install a parser and register your own Extractor implementation to extract real documents.

License

MIT © John Yaghobieh