Semantic context tracking for conversations.
Overview#
This library provides components for tracking semantic context in conversations
including topics, entities, and context compression. It works alongside
@iris/conversation-core to provide a complete conversation management
solution.
Features#
- TopicDetector - Detects and tracks conversation topics using keyword extraction and frequency analysis
- EntityTracker - Extracts and tracks named entities (people, organizations, emails, dates, etc.)
- ContextCompressor - Compresses conversation context while preserving key information
- ContextSummarizer - Creates and manages conversation summaries at various levels
- ContextTracker - Unified context management orchestrating all components
Installation#
bash
pnpm add @iris/conversation-context
Usage#
Basic Context Tracking#
typescript
import { createContextTracker } from '@iris/conversation-context';
// Create a context tracker for a conversation
const tracker = createContextTracker(conversationId);
// Process messages as they arrive
tracker.processMessage(message);
// Get context formatted for model input
const context = tracker.getContextForModel();
console.log('Summary:', context.summary);
console.log('Active Topics:', context.activeTopics);
console.log('Key Entities:', context.keyEntities);
Topic Detection#
typescript
import { createTopicDetector } from '@iris/conversation-context';
const detector = createTopicDetector({
minConfidence: 0.6,
maxActiveTopics: 5,
});
// Process messages
detector.processMessage(message);
// Get active topics
const activeTopics = detector.getActiveTopics();
const primaryTopic = detector.getPrimaryTopic();
// Check for topic shifts
const shifts = detector.getTopicShifts();
Entity Extraction#
typescript
import { createEntityTracker } from '@iris/conversation-context';
const tracker = createEntityTracker({
enabledTypes: ['person', 'organization', 'email', 'date'],
enableCoreference: true,
});
// Process messages
const mentions = tracker.processMessage(message);
// Get all entities
const entities = tracker.getAllEntities();
const emailEntities = tracker.getEntitiesByType('email');
// Find specific entity
const person = tracker.findEntity('John Smith', 'person');
Context Compression#
typescript
import { createContextCompressor } from '@iris/conversation-context';
const compressor = createContextCompressor({
strategy: 'hybrid',
targetRatio: 0.3,
});
// Compress messages
const result = compressor.compress(messages, topics, entities);
console.log(
'Compressed from',
result.originalTokens,
'to',
result.compressedTokens
);
console.log('Key points:', result.keyPoints);
Context Summarization#
typescript
import { createContextSummarizer } from '@iris/conversation-context';
const summarizer = createContextSummarizer({
type: 'rolling',
includeKeyPoints: true,
includeActionItems: true,
});
// Create summary
const summary = summarizer.summarize(messages, topics, entities);
console.log('Summary:', summary.text);
console.log('Action items:', summary.actionItems);
API Reference#
ContextTracker#
Main orchestration class for context tracking.
typescript
const tracker = createContextTracker(conversationId, config);
// Process messages
tracker.processMessage(message, turnId);
// Get state
const state = tracker.getState();
// Get context for model
const context = tracker.getContextForModel();
// Manual additions
tracker.addTopic(name, keywords, confidence);
tracker.addEntity(type, value, attributes);
tracker.addContextItem(type, content, importance);
// Summarization and compression
tracker.summarize();
tracker.compress();
TopicDetector#
Detects and tracks conversation topics.
typescript
const detector = createTopicDetector(config);
detector.processMessage(message);
detector.getActiveTopics();
detector.getPrimaryTopic();
detector.getTopicShifts();
detector.addTopic(name, keywords, confidence);
EntityTracker#
Extracts and tracks named entities.
typescript
const tracker = createEntityTracker(config);
tracker.processMessage(message);
tracker.getAllEntities();
tracker.getEntitiesByType(type);
tracker.findEntity(value, type);
tracker.addEntity(type, value, attributes);
ContextCompressor#
Compresses conversation context.
typescript
const compressor = createContextCompressor(config);
compressor.compress(messages, topics, entities);
compressor.compressIncremental(existingSummary, newMessages, topics, entities);
compressor.shouldCompress(currentTokens, maxTokens);
ContextSummarizer#
Creates conversation summaries.
typescript
const summarizer = createContextSummarizer(config);
summarizer.summarize(messages, topics, entities);
summarizer.addIncremental(messages, topics, entities);
summarizer.summarizeBySegments(messages, segmentSize);
summarizer.getCurrentRollingSummary();
Configuration#
TopicDetectorConfig#
typescript
interface TopicDetectorConfig {
minConfidence: number; // Default: 0.5
maxActiveTopics: number; // Default: 5
contextWindowSize: number; // Default: 10
enableHierarchicalTopics: boolean;
enableTopicRelationships: boolean;
minKeywordFrequency: number;
customKeywords?: Record<string, string[]>;
}
EntityTrackerConfig#
typescript
interface EntityTrackerConfig {
enabledTypes: EntityType[]; // Default: common types
minConfidence: number; // Default: 0.6
maxEntities: number; // Default: 100
enableCoreference: boolean; // Default: true
enableKnowledgeLinking: boolean;
customPatterns?: EntityPattern[];
}
ContextTrackerConfig#
typescript
interface ContextTrackerConfig {
topicDetector: TopicDetectorConfig;
entityTracker: EntityTrackerConfig;
maxDetailedMessages: number;
enableAutoPruning: boolean;
importanceDecayRate: number;
enablePersistence: boolean;
autoSummarizeThreshold: number;
}
License#
MIT