@reaatech/context-window-planner

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Canonical TypeScript types, packing strategies, tokenizer adapters, and context item primitives for managing LLM context windows. This package is the single source of truth for deciding what to include, what to summarize, and what to drop when packing prompts for Claude, GPT, and other LLMs.

Installation

npm install @reaatech/context-window-planner
# or
pnpm add @reaatech/context-window-planner

Feature Overview

• 88 exported types, classes, and factories — every context packing concept has a corresponding implementation
• 6 typed context item primitives — SystemPrompt, ConversationTurn, RAGChunk, ToolSchema, ToolResult, GenerationBuffer
• 4 packing strategies — priority-greedy, sliding-window, summarize-and-replace, and RAG relevance selection
• 3 tokenizer adapters — OpenAI (tiktoken), Anthropic (approximate), and mock (for testing)
• 7 typed error classes — all extend ContextPlannerError with stable error codes
• Pluggable architecture — custom strategies, tokenizers, summarizers, and item types via interfaces
• Deterministic and framework-agnostic — zero runtime dependencies beyond js-tiktoken
• Dual ESM/CJS output — works with import and require

Quick Start

import {
  ContextPlannerBuilder,
  createTokenizer,
  createPriorityGreedyStrategy,
  createSystemPrompt,
  createConversationTurn,
  createGenerationBuffer,
  Priority,
} from "@reaatech/context-window-planner";
 
const tokenizer = createTokenizer("gpt-4");
 
const planner = new ContextPlannerBuilder()
  .withBudget(8000)
  .withReserved(1000)
  .withTokenizer(tokenizer)
  .withStrategy(createPriorityGreedyStrategy())
  .build();
 
planner.addAll([
  createSystemPrompt({ content: "You are a helpful assistant." }, tokenizer),
  createConversationTurn({ role: "user", content: "Hello!" }, tokenizer),
  createGenerationBuffer({ reservedTokens: 500 }),
]);
 
const result = planner.pack();
console.log(result.included.length, "items fit");
console.log(result.summarize.length, "items to summarize");
console.log(result.dropped.length, "items dropped");
console.log(result.warnings); // machine-readable warnings

API Reference

Context Items

Six built-in item types with factory functions that auto-compute tokenCount:

All items implement the ContextItem interface (id, type, priority, tokenCount, canSummarize(), summarize?()). Summarizable items also implement Summarizable which adds estimatedSummarizedTokenCount and guarantees a summarize(targetTokens?) method.

Packing Strategies

Create strategies via the centralized factory:

import { strategies } from "@reaatech/context-window-planner";
 
const greedy = strategies.create("priority-greedy");
const window = strategies.create("sliding-window", { windowSize: 10 });
const replace = strategies.create("summarize-replace", { compressionRatio: 0.3 });
const rag = strategies.create("rag-selection", { ragBudgetRatio: 0.4, minRelevanceScore: 0.6 });

Or use the direct factory functions: createPriorityGreedyStrategy(), createSlidingWindowStrategy(opts), createSummarizeAndReplaceStrategy(opts), createRAGSelectionStrategy(opts).

Planner & Builder

Token Budget

Packing Result

Every pack() call returns a PackingResult:

Tokenizer Adapters

import { tokenizers } from "@reaatech/context-window-planner";
 
const gpt4 = tokenizers.create("gpt-4");
const claude = tokenizers.create("claude-3-opus-20240229");
const mock = tokenizers.create("mock");

Or use createTokenizer(model) as a convenience alias.

Error Classes

All errors extend ContextPlannerError which includes code: string, message: string, and optional details?: Record<string, unknown>.

import { ContextPlannerError } from "@reaatech/context-window-planner";
 
try {
  const result = planner.pack();
} catch (err) {
  if (err instanceof ContextPlannerError) {
    console.error(err.code, err.message, err.details);
  }
}

Utilities

Custom Strategies

Implement the PackingStrategy interface:

import type {
  PackingStrategy,
  PackingContext,
  PackingResult,
} from "@reaatech/context-window-planner";
 
class MyStrategy implements PackingStrategy {
  readonly name = "my-strategy";
 
  execute(context: PackingContext): PackingResult {
    // decide which items go into `included`, `summarize`, or `dropped`
    // and return usedTokens / remainingTokens / warnings
  }
}
 
const planner = new ContextPlanner({ budget: 128000, tokenizer, strategy: new MyStrategy() });

Related Packages

• @reaatech/context-window-planner-cli — CLI tool for reading context items from stdin and producing a packing plan

Examples

Runnable examples live in the repository under examples/:

License

MIT