# @iris/conversation-context

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