Skip to main content

API Reference (Python)

The complete Python API for LLM Context Forge. All critical operations are available from the root package.

TokenCounter​

Provides exact, deterministic token counting for a specified model.

from llm_context_forge import TokenCounter

counter = TokenCounter("gpt-4o")

Methods​

count(text: str) -> int​

Calculates the exact token count for the given text.

fits_in_window(text: str, reserve_output: int = 0) -> bool​

Returns True if the text token count + reserve_output is less than or equal to the model's context window.

DocumentChunker​

Splits text into token-safe chunks based on an intelligent strategy.

from llm_context_forge import DocumentChunker, ChunkStrategy

chunker = DocumentChunker("gpt-4o")

Methods​

chunk(text: str, strategy: ChunkStrategy, max_tokens: int, overlap_tokens: int = 0) -> list[str]​

Splits text using strategy so that no chunk exceeds max_tokens. overlap_tokens are duplicated between chunks.

ContextWindow​

Provides priority-based packing for LLM context assembly.

from llm_context_forge import ContextWindow, Priority

window = ContextWindow("claude-3-5-sonnet")

Methods​

add_block(content: str, priority: Priority, block_id: str = None) -> None​

Adds text to the window queue. Priority.CRITICAL (0) blocks will raise a ContextOverflowError if they don't fit.

assemble(max_tokens: int = None) -> str​

Packs the blocks in priority order until max_tokens (or the model's window) is reached. Returns the combined string.

usage() -> UsageStats​

Returns an object containing tokens_used, included (list of block IDs), and excluded (list of block IDs).

CostCalculator​

Calculates pricing estimates for prompts and completions.

from llm_context_forge import CostCalculator

calc = CostCalculator("gpt-4o")

Methods​

estimate_prompt(text: str) -> CostEstimate​

Returns an object containing the .usd cost of the input.

compare_models(texts: list[str], models: list[str]) -> list[ComparisonReport]​

Calculates the total cost of texts across all specified models and returns a list sorted by cheapest first.