Skip to main content

​
Overview

The context-window library provides a simple, type-safe API for building RAG (Retrieval-Augmented Generation) applications. The API is designed to be intuitive while offering powerful customization options.

​
Installation

npm install context-window

​
Basic Import

All main functions are exported from the root package: 
import {
  createCtxWindow,
  createCtxWindow,
  getCtxWindow,
  hasCtxWindow,
  deleteCtxWindow,
  clearCtxWindows,
  listCtxWindows
} from "context-window";

​
Quick Start

The simplest way to use context-window: 
import { createCtxWindow } from "context-window";

const cw = await createCtxWindow({
  namespace: "my-docs",
  data: ["./documents"],
  ai: { provider: "openai" },
  vectorStore: { provider: "pinecone" }
});

const result = await cw.ask("What is this about?");
console.log(result.text);

​
API Patterns

context-window offers two main patterns for managing context windows:

​
Direct Pattern

Create and use a context window directly: 
const cw = await createCtxWindow({ /* options */ });
const result = await cw.ask("Your question");
Best for: Single-use scenarios, scripts, simple applications

​
Registry Pattern

Create, register, and retrieve context windows by name: 
// Create and register
await createCtxWindow({ namespace: "docs", /* ... */ });

// Retrieve later (same process or different module)
const cw = getCtxWindow("docs");
const result = await cw.ask("Your question");
Best for: Multiple context windows, complex applications, modular architectures

​
Core Concepts

​
Context Window

A Context Window is an instance that manages:
  • Document ingestion and chunking
  • Vector embeddings and storage
  • Semantic search and retrieval
  • Answer generation with source citations

​
Index Name

Each context window requires a unique index name that:
  • Identifies the Pinecone namespace for data isolation
  • Serves as the key for the registry pattern
  • Should be descriptive (e.g., "user-manual", "api-docs")

​
Idempotency

context-window is idempotent by design:
  • Same files → same chunk IDs → updates instead of duplicates
  • Safe to re-run ingestion without creating redundant data
  • Content-based hashing ensures consistency

​
API Organization

Core Functions

Main functions for creating and managing context windows

Configuration

Detailed configuration options for AI, storage, chunking, and limits

Utility Functions

Helper functions for the registry pattern

ask() Method

Query your context window for answers

​
Type Safety

context-window is written in TypeScript with full type definitions: 
interface CreateContextWindowOptions {
  namespace: string;
  data: string | string[];
  ai?: AIConfig;
  vectorStore?: VectorStoreConfig;
  chunk?: ChunkConfig;
  limits?: LimitsConfig;
}

interface AskResult {
  text: string;
  sources: string[];
}
All types are exported and available for your TypeScript projects.

​
Environment Variables

Required environment variables:
VariableRequiredDescription
OPENAI_API_KEYYesOpenAI API key for embeddings and completions
PINECONE_API_KEYYesPinecone API key for vector storage
PINECONE_INDEXNoDefault Pinecone index name (default: "context-window")
PINECONE_ENVIRONMENTNoPinecone region (default: "us-east-1")

​
Error Handling

All functions use standard error handling patterns: 
try {
  const cw = await createCtxWindow({
    namespace: "my-docs",
    data: ["./documents"],
    ai: { provider: "openai" },
    vectorStore: { provider: "pinecone" }
  });

  const result = await cw.ask("Your question");
} catch (error) {
  if (error instanceof Error) {
    console.error("Error:", error.message);
  }
}
Common errors:
  • Invalid API keys: Check your .env configuration
  • Index not found: Ensure your Pinecone index exists
  • Incorrect dimensions: Pinecone index must have 1536 dimensions
  • File not found: Verify file paths in the data parameter

​
Next Steps

createCtxWindow

Learn about the direct creation pattern

createCtxWindow

Explore the registry pattern

Configuration Options

Customize AI models, chunking, and retrieval

Examples

See complete code examples