# Glyph Visual-Text Compression for AbstractCore

**Glyph** is a revolutionary visual-text compression system integrated into AbstractCore that transforms long textual sequences into optimized images for processing by Vision-Language Models (VLMs), achieving **3-4x token compression** without accuracy loss.

## Overview

Glyph addresses the fundamental challenge of long-context processing by reimagining how we handle large documents:

```
Traditional Approach:
Long Text (1M tokens) → Tokenization → Sequential Processing → Context Overflow

Glyph Approach:  
Long Text (1M tokens) → Visual Rendering → Image Processing (250K tokens) → VLM Interpretation
```

### Key Benefits

- **3-4x Token Compression**: Proven compression ratios with maintained quality
- **4x Faster Inference**: Significant speed improvements for large documents
- **Universal Provider Support**: Works across all vision-capable providers
- **Transparent Integration**: Automatic compression with intelligent fallback
- **Cost Optimization**: Direct cost savings through token reduction

## Quick Start

### Basic Usage

```python
from abstractcore import create_llm

# Automatic compression for large documents
llm = create_llm("openai", model="gpt-4o")
response = llm.generate(
    "Analyze this document for key insights",
    media=["large_report.pdf"],  # Automatically compressed if beneficial
    glyph_compression="auto"     # Default behavior
)

print(f"Compression used: {response.metadata.get('compression_ratio', 'None')}")
```

### Explicit Compression Control

```python
from abstractcore.compression import GlyphConfig

# Custom compression configuration
glyph_config = GlyphConfig(
    enabled=True,
    quality_threshold=0.95,
    target_compression_ratio=3.5,
    provider_optimization=True
)

llm = create_llm("anthropic", model="claude-3-5-sonnet", glyph_config=glyph_config)

# Force compression
response = llm.generate(
    "Summarize this content",
    media=["document.pdf"],
    glyph_compression="always"
)
```

## How It Works

### Rendering Pipeline

Glyph uses a sophisticated rendering pipeline based on the original research:

1. **Text Analysis**: Content type detection and optimization assessment
2. **PDF Generation**: High-quality text rendering using ReportLab
3. **Image Conversion**: Optimized image generation with provider-specific settings
4. **Quality Validation**: Multi-metric quality assessment with fallback
5. **Caching**: Intelligent caching for repeated content

### Provider Optimization

Glyph automatically optimizes rendering parameters for each provider:

| Provider | DPI | Font Size | Quality Focus |
|----------|-----|-----------|---------------|
| **OpenAI** | 72 | 9pt | Dense text, aggressive compression |
| **Anthropic** | 96 | 10pt | Font clarity, conservative settings |
| **Ollama** | 72 | 9pt | Balanced approach, auto-cropping |
| **LMStudio** | 96 | 10pt | Quality-focused rendering |

## Configuration

### Global Configuration

```python
from abstractcore.compression import GlyphConfig

# Create configuration
config = GlyphConfig(
    enabled=True,
    global_default="auto",           # auto, always, never
    quality_threshold=0.95,          # Minimum quality score
    target_compression_ratio=3.0,    # Target compression ratio
    cache_directory="~/.abstractcore/glyph_cache",
    provider_optimization=True
)

# Save to AbstractCore config
config.save_to_abstractcore_config()
```

### Provider-Specific Settings

```python
# Customize provider profiles
config.provider_profiles["openai"] = {
    "dpi": 72,
    "font_size": 9,
    "quality_threshold": 0.93,
    "newline_markup": '<font color="#FF0000"> \\n </font>'
}

config.provider_profiles["anthropic"] = {
    "dpi": 96,
    "font_size": 10,
    "quality_threshold": 0.96,
    "font_path": "Verdana.ttf"
}
```

### App-Specific Defaults

```python
# Set compression preferences per application
config.app_defaults = {
    "summarizer": "always",    # Always compress for document summarization
    "extractor": "never",      # Never compress for knowledge extraction
    "judge": "auto",          # Auto-detect for document evaluation
    "cli": "auto"             # Auto-detect for CLI usage
}
```

## Advanced Usage

### Compression Orchestrator

```python
from abstractcore.compression import CompressionOrchestrator

orchestrator = CompressionOrchestrator()

# Get detailed compression recommendation
recommendation = orchestrator.get_compression_recommendation(
    content="Your long text content...",
    provider="openai",
    model="gpt-4o"
)

print(f"Should compress: {recommendation['should_compress']}")
print(f"Estimated ratio: {recommendation['compression_estimate']['estimated_ratio']:.1f}x")
print(f"Token savings: {recommendation['compression_estimate']['estimated_token_savings']}")
print(f"Reason: {recommendation['recommendation_reason']}")
```

### Quality Assessment

```python
from abstractcore.compression.quality import QualityValidator

validator = QualityValidator()

# Assess compression quality
quality_score = validator.assess(
    original_content="Your text...",
    rendered_images=[Path("image1.png"), Path("image2.png")],
    provider="openai"
)

print(f"Quality score: {quality_score:.1%}")
```

### Session-Level Compression

```python
from abstractcore import BasicSession

# Enable compression for entire session
session = BasicSession(llm, glyph_compression="auto")

# Process multiple documents
response1 = session.generate("Analyze this report", media=["report1.pdf"])
response2 = session.generate("Compare with this document", media=["report2.pdf"])

# Get compression analytics
analytics = session.get_compression_analytics()
print(f"Total token savings: {analytics['total_token_savings']:,}")
print(f"Average compression ratio: {analytics['average_compression_ratio']:.1f}x")
```

## Performance Characteristics

### Compression Effectiveness

| Content Type | Compression Ratio | Quality Score | Use Case |
|--------------|-------------------|---------------|----------|
| **Prose/Natural Language** | 3-4x | 95-98% | Documents, articles, reports |
| **Code** | 2-3x | 90-95% | Source code, technical docs |
| **Structured Data** | 2x | 85-90% | JSON, CSV, configuration files |
| **Mixed Content** | 2.5-3.5x | 90-95% | Technical documentation |

### Processing Times

- **First Compression**: 5-30 seconds (includes optimization)
- **Cached Compression**: 1-5 seconds (reuses configuration)
- **Quality Validation**: <1 second
- **Net Processing Time**: Often faster due to 4x inference speedup

## Best Practices

### When to Use Compression

✅ **Recommended for:**
- Documents > 10,000 tokens
- Prose and natural language content
- Technical documentation
- Research papers and reports
- Large configuration files

❌ **Not recommended for:**
- Mathematical notation (OCR challenges)
- Very dense special characters
- Content < 5,000 tokens
- Real-time chat applications

### Provider Selection

- **OpenAI GPT-4o**: Excellent OCR, handles dense text well
- **Anthropic Claude**: Good OCR, font-sensitive, quality-focused
- **Ollama qwen2.5vl**: Balanced performance, good for local deployment
- **LMStudio**: Variable quality, depends on specific model

### Quality Optimization

```python
# High-quality compression for critical applications
config = GlyphConfig(
    quality_threshold=0.98,        # Higher quality requirement
    target_compression_ratio=2.5,  # Conservative compression
    provider_optimization=True     # Use provider-specific settings
)

# Performance-focused compression
config = GlyphConfig(
    quality_threshold=0.90,        # Lower quality for speed
    target_compression_ratio=4.0,  # Aggressive compression
    cache_size_gb=2.0              # Larger cache for repeated content
)
```

## Troubleshooting

### Common Issues

**Compression Quality Too Low**
```python
# Increase quality threshold
config.quality_threshold = 0.98

# Use conservative provider settings
config.provider_profiles["anthropic"]["dpi"] = 96
config.provider_profiles["anthropic"]["font_size"] = 11
```

**Compression Failing**
```python
# Check provider vision support
from abstractcore.media.capabilities import get_model_capabilities
capabilities = get_model_capabilities("openai", "gpt-4o")
print(f"Vision support: {capabilities.get('vision_support', False)}")

# Enable debug logging
import logging
logging.getLogger('abstractcore.compression').setLevel(logging.DEBUG)
```

**Performance Issues**
```python
# Optimize cache settings
config.cache_size_gb = 5.0
config.cache_ttl_days = 30

# Use background processing
config.max_concurrent_compressions = 4
```

### Error Handling

```python
from abstractcore.compression.exceptions import CompressionError, CompressionQualityError

try:
    response = llm.generate("Analyze document", media=["doc.pdf"])
except CompressionQualityError as e:
    print(f"Quality too low: {e.quality_score} < {e.threshold}")
    # Retry with higher quality settings
except CompressionError as e:
    print(f"Compression failed: {e}")
    # Fallback to standard processing
```

## Integration Examples

### CLI Applications

```bash
# Note: built-in CLI apps currently don't expose a `--glyph-compression` flag.
# Use the Python API (below) or implement a thin wrapper in your own CLI.
```

### HTTP Server

```python
import requests

# Note: the OpenAI-compatible server does not currently expose a `glyph_compression`
# request field. Use the Python API, or extend the server request schema to pass it through.
response = requests.post(
    "http://localhost:8000/v1/chat/completions",
    json={
        "model": "openai/gpt-4o",
        "messages": [{"role": "user", "content": "Analyze @large_report.pdf"}],
    }
)
```

### Production Deployment

```python
from abstractcore.compression import GlyphConfig

# Production-grade configuration
config = GlyphConfig(
    quality_threshold=0.98,
)

llm = create_llm("openai", model="gpt-4o", glyph_config=config)
```

## Research Background

Glyph is based on the research paper "Glyph: Scaling Context Windows via Visual-Text Compression" by Z.ai/THU-COAI. The implementation in AbstractCore includes:

- **Proven Benchmarks**: Validated on LongBench, MRCR, and RULER evaluations
- **Production Optimizations**: Enhanced error handling, caching, and provider support
- **Universal Integration**: Works across all AbstractCore-supported providers
- **Quality Assurance**: Multi-metric validation with automatic fallback

## Dependencies

### Required
- `PIL/Pillow`: Image processing and optimization

### Optional (advanced)
- `pdf2image` (+ system dependencies): direct PDF→image conversion path (otherwise falls back to text extraction)
- `pip install "abstractcore[media]"`: PDF/Office text extraction (PyMuPDF4LLM, unstructured, ...)

### Installation
```bash
# Install with compression support
pip install "abstractcore[compression]"

# For PDFs/Office documents (text extraction)
pip install "abstractcore[media]"
```

## Conclusion

Glyph compression represents a paradigm shift in long-context processing, offering significant performance and cost benefits while maintaining quality. Its seamless integration with AbstractCore makes it easy to adopt incrementally, with automatic fallback ensuring robust operation.

For more information, see the [Glyph research paper](https://arxiv.org/abs/2510.17800) and the [AbstractCore documentation](../README.md).