Context Window API Reference

API specification for the Context Window Management system. For conceptual explanation, see Context Window Management.

Configuration

ContextWindowConfig

Configuration class for the Context Window Management system.

from babylon.rag.context_window import ContextWindowConfig

class ContextWindowConfig:
    """Configuration for Context Window Management."""
    max_token_limit: int = 150000
    capacity_threshold: float = 0.75
    prioritization_strategy: str = "hybrid"
    min_content_importance: float = 0.2
Configuration Parameters

Parameter

Default

Description

max_token_limit

150000

Maximum tokens allowed in context window

capacity_threshold

0.75

Percentage at which auto-optimization triggers

prioritization_strategy

"hybrid"

Strategy for content ordering (see below)

min_content_importance

0.2

Minimum importance score to retain during optimization

Prioritization Strategies

Strategy

Description

relevance

Prioritizes based on importance score only

recency

Prioritizes based on access time only

hybrid

Combines importance, recency, and frequency (default)

Token Capacity

Theoretical Limits

Based on 200k token context window:

Object Type

Token Estimate

Max Objects

Simple Entity

~100 tokens

400-600

Complex Contradiction

~300-500 tokens

200-300

Relationship Network

~200-400 tokens/network

Variable

Event Chain

~200-300 tokens

Variable

Token Usage by Component

Component

Token Range

Object metadata

10-20 tokens

Core attributes

30-50 tokens

Relationships

20-40 tokens per connection

Historical data

50-100 tokens

State information

30-50 tokens

Working Set Tiers

Immediate Context (Active Memory)

Size

20-30 objects

Update frequency

Every game tick

Access latency

<10ms

Memory footprint

~5k tokens

Active Cache

Size

100-200 objects

Update frequency

As needed

Access latency

<100ms

Memory footprint

~30k tokens

Background Context

Size

300-500 objects

Update frequency

Periodic

Access latency

<500ms

Memory footprint

~60k tokens

API Classes

ContextWindowManager

Central class for managing the context window.

from babylon.rag.context_window import ContextWindowManager, ContextWindowConfig
from babylon.metrics.collector import MetricsCollector

# Initialize
config = ContextWindowConfig(max_token_limit=100000)
metrics = MetricsCollector()
manager = ContextWindowManager(config=config, metrics_collector=metrics)

Methods:

Method

Description

add_content(content_id, content, token_count, importance)

Add content to context window

get_content(content_id)

Retrieve content by ID

remove_content(content_id)

Remove content from context window

optimize(target_tokens)

Manually trigger optimization

get_stats()

Get current statistics

ObjectMetrics

Performance metrics for tracked objects.

class ObjectMetrics:
    access_count: int = 0
    cache_hits: int = 0
    cache_misses: int = 0
    token_usage: int = 0
    load_time: float = 0.0
    last_access: datetime | None = None
    relationship_count: int = 0

ObjectManager

Lifecycle management for game objects.

class ObjectManager:
    active_objects: LRUCache  # max_size=30
    cached_objects: LRUCache  # max_size=200
    metrics: MetricsCollector

Methods:

Method

Description

get_object(object_id)

Retrieve object with caching

_promote_to_active(object_id)

Move object from cache to active

_load_from_vector_db(object_id)

Load object from ChromaDB

MetricsCollector

Performance monitoring and analysis.

class MetricsCollector:
    logs: dict  # access_patterns, token_usage, cache_performance, latency_metrics

Methods:

Method

Description

record_access(object_id)

Record object access event

record_cache_hit(cache_level)

Record cache hit (active/secondary)

record_cache_miss()

Record cache miss

analyze_performance()

Generate performance analysis report

Usage Examples

Basic Content Management

from babylon.rag.context_window import ContextWindowManager, ContextWindowConfig

# Create manager
config = ContextWindowConfig(
    max_token_limit=100000,
    capacity_threshold=0.8,
    prioritization_strategy="hybrid"
)
manager = ContextWindowManager(config=config)

# Add content
manager.add_content(
    content_id="document1",
    content="Sample document text",
    token_count=5,
    importance=0.8
)

# Retrieve content
content = manager.get_content("document1")

# Remove content
manager.remove_content("document1")

# Get statistics
stats = manager.get_stats()

Handling Capacity Errors

from babylon.rag.context_window import CapacityExceededError

try:
    manager.add_content("large_doc", "..." * 10000, 30000, 0.5)
except CapacityExceededError as e:
    print(f"Error {e.code}: {e}")
    manager.optimize(target_tokens=50000)

Error Codes

Context window errors use codes in the 2100-2199 range. See Error Codes for the complete taxonomy.

Code

Description

2100

Base Context Window Error

2101

Token Count Error

2102

Capacity Exceeded Error

2103

Optimization Failed Error

2110-2112

Content Operation Errors

2120-2122

Integration Errors

See Also