@ooples/token-optimizer-mcp
Version:
Intelligent context window optimization for Claude Code - store content externally via caching and compression, freeing up your context window for what matters
412 lines • 13.3 kB
TypeScript
/**
* CachePartition - Cache Partitioning & Sharding
* 87%+ token reduction through partition metadata caching and statistics aggregation
*
* Features:
* - Multiple partitioning strategies (hash, range, category, geographic, custom)
* - Consistent hashing with virtual nodes
* - Automatic rebalancing on partition add/remove
* - Hot partition detection and splitting
* - Cross-partition queries (scatter-gather)
* - Partition-level TTL and eviction policies
* - Partition isolation for multi-tenancy
*
* Operations:
* 1. create-partition - Create new cache partition
* 2. delete-partition - Delete cache partition
* 3. list-partitions - List all partitions
* 4. migrate - Migrate keys between partitions
* 5. rebalance - Rebalance partitions
* 6. configure-sharding - Configure sharding strategy
* 7. stats - Get partition statistics
*/
import { EventEmitter } from 'events';
import { CacheEngine } from '../../core/cache-engine.js';
import { TokenCounter } from '../../core/token-counter.js';
import { MetricsCollector } from '../../core/metrics.js';
export interface CachePartitionOptions {
operation: 'create-partition' | 'delete-partition' | 'list-partitions' | 'migrate' | 'rebalance' | 'configure-sharding' | 'stats';
partitionId?: string;
strategy?: 'hash' | 'range' | 'category' | 'geographic' | 'custom';
sourcePartition?: string;
targetPartition?: string;
keyPattern?: string;
targetDistribution?: 'even' | 'weighted' | 'capacity-based';
maxMigrations?: number;
shardingStrategy?: 'consistent-hash' | 'range' | 'custom';
virtualNodes?: number;
partitionFunction?: string;
includeKeyDistribution?: boolean;
includeMemoryUsage?: boolean;
useCache?: boolean;
cacheTTL?: number;
}
export interface PartitionInfo {
id: string;
strategy: 'hash' | 'range' | 'category' | 'geographic' | 'custom';
status: 'active' | 'migrating' | 'draining' | 'inactive';
keyCount: number;
memoryUsage: number;
virtualNodes: number[];
createdAt: number;
lastAccessed: number;
metadata: Record<string, unknown>;
}
export interface MigrationPlan {
sourcePartition: string;
targetPartition: string;
keysToMigrate: string[];
estimatedDuration: number;
status: 'pending' | 'in-progress' | 'completed' | 'failed';
}
export interface RebalanceResults {
migrationsPerformed: number;
keysMoved: number;
newDistribution: Record<string, number>;
duration: number;
}
export interface ShardingConfig {
strategy: 'consistent-hash' | 'range' | 'custom';
virtualNodesPerPartition: number;
hashFunction: string;
partitionFunction?: string;
replicationFactor: number;
}
export interface PartitionStatistics {
totalPartitions: number;
totalKeys: number;
totalMemory: number;
averageKeysPerPartition: number;
loadImbalance: number;
hotPartitions: string[];
partitionDetails: Record<string, {
keyCount: number;
memoryUsage: number;
hitRate: number;
evictionRate: number;
}>;
}
export interface CachePartitionResult {
success: boolean;
operation: string;
data: {
partition?: PartitionInfo;
partitions?: PartitionInfo[];
migrationPlan?: MigrationPlan;
rebalanceResults?: RebalanceResults;
shardingConfig?: ShardingConfig;
statistics?: PartitionStatistics;
};
metadata: {
tokensUsed: number;
tokensSaved: number;
cacheHit: boolean;
executionTime: number;
};
}
interface PartitionKeyStore {
partitionId: string;
keys: Set<string>;
memoryUsage: number;
accessCounts: Map<string, number>;
lastAccessed: number;
}
/**
* CachePartition - Advanced cache partitioning and sharding
*/
export declare class CachePartitionTool extends EventEmitter {
private cache;
private tokenCounter;
private metrics;
private partitions;
private partitionStores;
private hashRing;
private shardingConfig;
private activeMigrations;
private partitionMetrics;
constructor(cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector);
/**
* Main entry point for all partition operations
*/
run(options: CachePartitionOptions): Promise<CachePartitionResult>;
/**
* Create a new cache partition
*/
private createPartition;
/**
* Delete a cache partition
*/
private deletePartition;
/**
* List all partitions
*/
private listPartitions;
/**
* Migrate keys between partitions
*/
private migrate;
/**
* Rebalance partitions
*/
private rebalance;
/**
* Configure sharding strategy
*/
private configureSharding;
/**
* Get partition statistics
*/
private getStatistics;
/**
* Add virtual nodes to consistent hash ring
*/
private addVirtualNodesToRing;
/**
* Remove virtual nodes from hash ring
*/
private removeVirtualNodesFromRing;
/**
* Hash a virtual node
*/
private hashVirtualNode;
/**
* Hash a key to find its partition
*/
private hashKey;
/**
* Find partition for a key using consistent hashing
*/
getPartitionForKey(key: string): string | null;
/**
* Perform migration asynchronously
*/
private performMigration;
/**
* Calculate current distribution
*/
private calculateDistribution;
/**
* Calculate target distribution
*/
private calculateTargetDistribution;
/**
* Plan rebalance migrations
*/
private planRebalanceMigrations;
/**
* Execute a single migration
*/
private executeSingleMigration;
/**
* Calculate load imbalance coefficient
*/
private calculateLoadImbalance;
/**
* Rebuild hash ring with new configuration
*/
private rebuildHashRing;
/**
* Determine if operation is cacheable
*/
private isCacheableOperation;
/**
* Get cache key parameters for operation
*/
private getCacheKeyParams;
/**
* Detect hot partitions that need splitting
*/
detectHotPartitions(threshold?: number): string[];
/**
* Split a hot partition into multiple partitions
*/
splitPartition(partitionId: string, targetCount?: number): Promise<string[]>;
/**
* Get partition health status
*/
getPartitionHealth(partitionId: string): {
healthy: boolean;
issues: string[];
recommendations: string[];
};
/**
* Export partition configuration
*/
exportConfiguration(): {
partitions: PartitionInfo[];
shardingConfig: ShardingConfig;
hashRing: {
nodeCount: number;
partitionCount: number;
};
};
/**
* Import partition configuration
*/
importConfiguration(config: {
partitions: PartitionInfo[];
shardingConfig: ShardingConfig;
}): void;
/**
* Merge multiple partitions into a single partition
*/
mergePartitions(partitionIds: string[], targetId: string): Promise<{
mergedPartition: PartitionInfo;
keysMerged: number;
deletedPartitions: string[];
}>;
/**
* Route a query to appropriate partition(s)
*/
routeQuery(key: string, options?: {
preferLocal?: boolean;
replicationFactor?: number;
}): {
primaryPartition: string;
replicaPartitions: string[];
};
/**
* Execute cross-partition scatter-gather query
*/
scatterGather<T>(operation: (partitionId: string, store: PartitionKeyStore) => Promise<T>, options?: {
partitions?: string[];
parallel?: boolean;
timeout?: number;
}): Promise<Map<string, T>>;
/**
* Get partition affinity for a set of keys
*/
getKeyAffinityMap(keys: string[]): Map<string, string[]>;
/**
* Optimize partition placement for locality
*/
optimizeLocality(keyGroups: Map<string, string[]>): Promise<{
recommendedMigrations: Array<{
keys: string[];
from: string;
to: string;
reason: string;
}>;
estimatedImprovement: number;
}>;
/**
* Set partition-level TTL policy
*/
setPartitionTTL(partitionId: string, ttl: number): void;
/**
* Set partition-level eviction policy
*/
setPartitionEvictionPolicy(partitionId: string, policy: 'LRU' | 'LFU' | 'FIFO' | 'TTL'): void;
/**
* Get partition topology visualization
*/
getTopologyVisualization(): {
nodes: Array<{
id: string;
type: 'partition' | 'virtual-node';
partitionId: string;
keyCount: number;
memoryUsage: number;
}>;
edges: Array<{
from: string;
to: string;
type: 'virtual-node' | 'migration' | 'replication';
}>;
};
/**
* Record key access for analytics
*/
recordKeyAccess(key: string, partitionId: string): void;
/**
* Record key miss for analytics
*/
recordKeyMiss(_key: string, partitionId: string): void;
/**
* Record key eviction for analytics
*/
recordKeyEviction(key: string, partitionId: string): void;
/**
* Cleanup and dispose
*/
dispose(): void;
}
export declare function getCachePartitionTool(cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector): CachePartitionTool;
export declare const CACHE_PARTITION_TOOL_DEFINITION: {
readonly name: "cache_partition";
readonly description: "Advanced cache partitioning and sharding with 87%+ token reduction through consistent hashing, automatic rebalancing, and partition isolation";
readonly inputSchema: {
readonly type: "object";
readonly properties: {
readonly operation: {
readonly type: "string";
readonly enum: readonly ["create-partition", "delete-partition", "list-partitions", "migrate", "rebalance", "configure-sharding", "stats"];
readonly description: "The partition operation to perform";
};
readonly partitionId: {
readonly type: "string";
readonly description: "Partition identifier (required for create/delete operations)";
};
readonly strategy: {
readonly type: "string";
readonly enum: readonly ["hash", "range", "category", "geographic", "custom"];
readonly description: "Partitioning strategy (default: hash)";
};
readonly sourcePartition: {
readonly type: "string";
readonly description: "Source partition for migration";
};
readonly targetPartition: {
readonly type: "string";
readonly description: "Target partition for migration";
};
readonly keyPattern: {
readonly type: "string";
readonly description: "Regex pattern for keys to migrate";
};
readonly targetDistribution: {
readonly type: "string";
readonly enum: readonly ["even", "weighted", "capacity-based"];
readonly description: "Target distribution strategy for rebalancing (default: even)";
};
readonly maxMigrations: {
readonly type: "number";
readonly description: "Maximum number of migrations during rebalance (default: 1000)";
};
readonly shardingStrategy: {
readonly type: "string";
readonly enum: readonly ["consistent-hash", "range", "custom"];
readonly description: "Sharding strategy configuration";
};
readonly virtualNodes: {
readonly type: "number";
readonly description: "Number of virtual nodes per partition (default: 150)";
};
readonly partitionFunction: {
readonly type: "string";
readonly description: "Custom partition function (JavaScript code)";
};
readonly includeKeyDistribution: {
readonly type: "boolean";
readonly description: "Include key distribution in statistics (default: true)";
};
readonly includeMemoryUsage: {
readonly type: "boolean";
readonly description: "Include memory usage in statistics (default: true)";
};
readonly useCache: {
readonly type: "boolean";
readonly description: "Enable result caching (default: true)";
readonly default: true;
};
readonly cacheTTL: {
readonly type: "number";
readonly description: "Cache TTL in seconds (default: 300)";
readonly default: 300;
};
};
readonly required: readonly ["operation"];
};
};
export {};
//# sourceMappingURL=cache-partition.d.ts.map