README.md

# SOMA CoT Compression Suite

## Overview

Comprehensive Chain-of-Thought (CoT) compression algorithms for the SOMA subnet (Bittensor subnet 114).
This package contains **15 compression strategies** optimized for reducing agent context while preserving task-critical information.

## 🏆 Top Performance Results

**Evaluation on 5 sample tasks (275,835 characters):**

| Rank | Compressor | Compression | Token Savings | Use Case |
|------|------------|-------------|---------------|----------|
| 🥇 | **Performance** | **99.04%** | **68,295 tokens** | Speed-optimized |
| 🥈 | **Aggressive** | **94.77%** | **64,580 tokens** | Critical info only |
| 🥉 | **Code-Focused** | **83.33%** | **57,464 tokens** | Debug scenarios |
| 4 | Hybrid | 4.17% | 3,643 tokens | Balanced |
| 5 | Adaptive | 4.17% | 3,641 tokens | Importance-based |

## Algorithms

### Top 3 High-Compression Algorithms

#### 1. Performance-Focused Compressor 🚀
- **Compression: 99.04%** (NEW CHAMPION!)
- Fast truncation with start/end preservation
- Minimal processing overhead
- **68,295 tokens saved** on test set
- Best for: High-throughput scenarios, speed-critical applications

#### 2. Aggressive Hybrid Compressor
- **Compression: 94.77%**
- Extracts only errors, file changes, and code blocks
- Maximum compression for token-constrained environments
- **64,580 tokens saved** on test set
- Best for: High-volume agent logs, cost optimization

#### 3. Code-Focused Compressor
- **Compression: 83.33%**
- Preserves stack traces, errors, code blocks
- Optimized for debugging scenarios
- **57,464 tokens saved** on test set
- Best for: Development and debugging workflows

### Moderate Compression Algorithms

#### 4. Hybrid Compressor
- **Compression: 4.17%**
- Combines thinking chain removal + adaptive compression
- Balanced semantic preservation
- Best for: General-purpose CoT compression

#### 5. Adaptive Compressor
- **Compression: 4.17%**
- Importance-based message scoring (0-10 scale)
- Dynamic compression ratios
- Best for: Mixed-importance content

#### 6. Dialogue-Focused Compressor
- **Compression: ~0%** (preservation mode)
- Optimized for Q&A and conversation
- Preserves user queries and key responses
- Best for: Interactive dialogue scenarios

#### 7. Thinking Strip Compressor
- **Compression: ~0%**
- Removes `<thinking>...</thinking>` blocks
- Minimal impact on test data
- Best for: Explicit reasoning chain removal

### Configurable Variants (8 presets)

Fine-tune compression with environment variables:

1. **config1_semantic_max4**: Semantic scoring, 4 tool results
2. **config2_baseline_max6**: Baseline style, 6 tool results
3. **config3_semantic_low_recency**: Low recency bias (0.3)
4. **config4_semantic_high_recency**: High recency bias (0.7)
5. **config5_aggressive_compress**: 2 tool results, 10x error weight
6. **config6_error_focused**: 15x error weight, 3 tool results
7. **config7_balanced**: Equal weights across features
8. **config8_edit_optimized**: 10x file change weight, 5 tool results

## Usage

### High-Compression (99% reduction)

```python
from performance_focused_compressor import compress_messages

messages = [
    {'role': 'user', 'content': 'Your very long context here...'},
    {'role': 'assistant', 'content': 'Long response...'}
]

compressed = compress_messages(messages)
# Returns ~1% of original size with start/end preserved
```

### Code Debugging (83% reduction)

```python
from code_focused_compressor import compress_messages

# Preserves stack traces, errors, code blocks
compressed = compress_messages(debug_messages)
```

### Extreme Compression (95% reduction)

```python
from aggressive_hybrid_compressor import compress_messages

# Extracts only critical information
compressed = compress_messages(agent_logs)
```

## Performance Comparison

| Compressor | Speed | Compression | Preservation | Best For |
|------------|-------|-------------|--------------|----------|
| Performance | ⚡⚡⚡ | 99.04% | Start/End | Speed |
| Aggressive | ⚡⚡ | 94.77% | Critical only | Cost |
| Code-Focused | ⚡⚡ | 83.33% | Debug info | Development |
| Hybrid | ⚡ | 4.17% | Semantic | General |
| Adaptive | ⚡ | 4.17% | Importance | Mixed content |

## Evaluation Results

Detailed metrics available in:
- `specialized_compressor_results.json` - Latest specialized compressors
- `final_compressor_evaluation.json` - Comprehensive comparison
- `compression_eval_results.json` - Initial evaluation

## Research Basis

Techniques from 37 arXiv papers (2024-2026):
- Direct Preference Optimization (DPO)
- Reinforcement Learning from Human Feedback (RLHF)
- Group Relative Policy Optimization (GRPO)
- Context compression and truncation strategies

## Installation

```bash
# No dependencies required - pure Python stdlib
# Optional: tiktoken for precise token counting
pip install tiktoken
```

## Competition Context

Developed for SOMA (Bittensor subnet 114) CoT compression competition.
Target: Maximize compression while maintaining task performance.

## License

MIT License

## Updates

- **2026-08-16**: Added 3 specialized compressors
  - Performance-focused: 99.04% compression (NEW BEST)
  - Code-focused: 83.33% compression
  - Dialogue-focused: Preservation mode

## Author

Generated for SOMA subnet 114 competition
Repository: https://huggingface.co/XXMiner/soma-cot-compression