# ARES Orchestrator Compression

**Drop-in context compression for LLM orchestrator agent stacks.**

This library provides three adapter surfaces for compressing LLM context while preserving semantic meaning:

- **OpenAICompressor** - Compresses OpenAI-style messages
- **TransformersCompressor** - Compresses token IDs for HuggingFace models
- **StringCompressor** - Compresses raw text

## What It Does

This library uses **sentence-level compression** to reduce token count while preserving semantic meaning:

1. **Splits text into sentences** - Maintains natural language boundaries
2. **Scores sentences by importance** - Using position, length, and uniqueness metrics
3. **Keeps high-scoring sentences** - In original order to maintain coherence
4. **Fallback chunking** - For boundary-poor text, uses word-window chunking to ensure compression
5. **Preserves structure** - Message boundaries, roles, and token IDs are maintained

## Compression Modes

| Mode | Compression Ratio | Use Case |
|------|------------------|----------|
| `conservative` | 20-30% reduction | Preserve maximum information |
| `balanced` | 40-50% reduction | Good balance of compression and meaning |
| `aggressive` | 60-70% reduction | Maximum compression, some meaning loss |

## Installation

```bash
pip install torch>=2.0.0

# Optional: for OpenAI message compression with accurate token counting
pip install tiktoken>=0.5.0
```

## Quick Start

### OpenAI Messages

```python
from ares_orchestrator_compression import OpenAICompressor

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Explain machine learning in detail. " * 20},
    {"role": "assistant", "content": "Machine learning is... " * 20},
]

compressor = OpenAICompressor(mode="balanced")
result = compressor.compress_messages(messages)

# Use with OpenAI API
import openai
response = openai.chat.completions.create(
    model="gpt-4",
    messages=result.compressed_messages
)

print(f"Tokens saved: {result.tokens_saved} ({result.compression_ratio:.1%})")
```

### Transformers Token IDs

```python
from ares_orchestrator_compression import TransformersCompressor

# Your token IDs from a tokenizer
token_ids = [1000, 2000, 3000, ...]  # 200 tokens

compressor = TransformersCompressor(mode="balanced")
result = compressor.compress_token_ids(token_ids)

# Use with HuggingFace
import torch
outputs = model.generate(
    input_ids=torch.tensor([result.compressed_token_ids]),
    attention_mask=torch.tensor([result.attention_mask])
)

print(f"Tokens saved: {result.tokens_saved}")
```

### String Compression

```python
from ares_orchestrator_compression import StringCompressor

text = "This is sentence one. This is sentence two. " * 50

compressor = StringCompressor(mode="balanced")
result = compressor.compress_string(text)

print(f"Original: {result.original_length} chars")
print(f"Compressed: {result.compressed_length} chars")
print(f"Saved: {result.compression_ratio:.1%}")
```

## How It Works

### Sentence-Level Compression

Unlike naive approaches that sample every Nth word (which destroys meaning), this approach:

1. **Preserves sentence boundaries** - Each compressed message contains complete sentences
2. **Maintains coherence** - Sentences are kept in their original order
3. **Scores by importance** - Considers:
   - **Position** - Earlier sentences are often more important
   - **Length** - Medium-length sentences are most informative
   - **Uniqueness** - Sentences with rare words are more valuable
4. **Handles boundary-poor text** - Falls back to word-window chunking for text with sparse punctuation

### Example

**Original** (3 sentences):
```
Machine learning is a subset of AI. It enables systems to learn from data. 
Deep learning uses neural networks with many layers. These algorithms are 
inspired by the human brain's structure.
```

**Compressed** (balanced mode, keeps 2 most important sentences):
```
Machine learning is a subset of AI. Deep learning uses neural networks 
with many layers.
```

The result is readable and preserves the core meaning while reducing tokens.

## Architecture

```
Input Messages/Tokens
         ↓
Sentence Splitter
         ↓
Importance Scorer (position + length + uniqueness)
         ↓
Top-K Selection (by mode)
         ↓
Output Compressed Messages/Tokens
```

## API Reference

### OpenAICompressor

```python
compressor = OpenAICompressor(mode="balanced", model_name="gpt-4")
result = compressor.compress_messages(messages)

# Result fields
result.original_length        # Original token count
result.compressed_length      # Compressed token count
result.compression_ratio      # Fraction of tokens removed
result.tokens_saved           # Number of tokens saved
result.compressed_messages    # Compressed OpenAI messages
result.latency_ms             # Compression time
```

### TransformersCompressor

```python
compressor = TransformersCompressor(mode="balanced")
result = compressor.compress_token_ids(
    token_ids, 
    attention_mask=None,
    sentence_boundaries=None  # Optional: list of (start, end) indices
)

# Result fields
result.original_length          # Original token count
result.compressed_length        # Compressed token count
result.compressed_token_ids     # Compressed token IDs
result.attention_mask           # Attention mask for compressed tokens
```

### StringCompressor

```python
compressor = StringCompressor(mode="balanced")
result = compressor.compress_string(text)

# Result fields
result.original_length      # Original character count
result.compressed_length    # Compressed character count
result.compressed_string    # Compressed text
result.chars_saved          # Number of characters saved
```

## Testing

Run the comprehensive test suite:

```bash
# Run all tests
python -m pytest -q

# Run the end-to-end demo
python run_demo.py
```

The demo includes:
- OpenAI message compression (conservative, balanced, aggressive modes)
- Transformers token ID compression
- String compression
- Message boundary preservation tests
- Edge cases including long boundary-poor text compression

## Limitations

1. **No semantic embeddings** - Importance is heuristic-based, not using sentence transformers
2. **Best for narrative text** - Works best on prose, less optimal for code or structured data
3. **Lossy compression** - Some information is lost; aggressive mode may remove important details
4. **Sentence splitting uses regex** - Falls back to chunking for text with sparse punctuation boundaries

## When to Use

**Good for:**
- Compressing chat history
- Reducing document context
- Pre-processing long prompts
- Saving API costs on long conversations

**Not ideal for:**
- Code or structured data (use dedicated compression)
- Exact text reproduction required
- Very short messages (< 100 tokens)

## License

MIT

## Contributing

Contributions welcome! Areas for improvement:
- Better sentence boundary detection
- Semantic embeddings for importance scoring
- Language-specific handling
- Configurable scoring weights

<!-- ARES_AUTO_VERIFIED_SUMMARY:START -->
## Verified Project Notes

- Package import path: `ares_orchestrator_compression`
- Entrypoint: `run_demo.py`
- Delivery mode: `prototype`
- Release tier: `prototype`
- Verification status: `FAIL`
- Clean-room release gates: `NOT_RUN`
- Public exports: `CompressionConfig, CompressionMode, CompressionResult, OpenAICompressionResult, OpenAICompressor, StringCompressionResult, StringCompressor, TransformersCompressionResult, TransformersCompressor`
- Python files detected: `run_demo.py, test_all_adapters.py, test_comprehensive.py, test_quality.py, test_quality_simple.py, test_simple.py, ares_orchestrator_compression/__init__.py, ares_orchestrator_compression/adapters.py`

## Verification Commands

- `PASS` `"Q:\ARES\.venv-cuda311\Scripts\python.exe" -m py_compile "run_demo.py" "test_all_adapters.py" "test_comprehensive.py" "test_quality.py" "tes`
- `PASS` `"Q:\ARES\.venv-cuda311\Scripts\python.exe" -m compileall "ares_orchestrator_compression" "tests"`
- `FAIL` `"Q:\ARES\.venv-cuda311\Scripts\python.exe" run_demo.py`
- `FAIL` `"Q:\ARES\.venv-cuda311\Scripts\python.exe" -m pytest -q`

## Current Limits

- README markets the project as drop-in or plug-and-play, but clean-room release gates have not passed.
- Workspace contains workaround or duplicate variant files instead of a single canonical implementation: test_all_adapters.py, test_comprehensive.py, test_quality.py, test_quality_simple.py, test_simple.py, ares_orchestrator_compression/adapters_fixed.py
- Verification failure: Q:\ARES\.venv-cuda311\Lib\site-packages\torch\cuda\__init__.py:65: FutureWarning: The pynvml package is deprecated. Please install nvidia-ml-py instead. If you did not install pynvml directly, please
- Orchestration hardening failed: No module named 'litellm'
<!-- ARES_AUTO_VERIFIED_SUMMARY:END -->