Contextuals v0.2.2

[0.2.2] - 2025-05-30

🐛 Critical Bug Fixes

Fixed macOS Memory Calculation - Major Accuracy Improvement

• CRITICAL FIX: Corrected memory reporting on Apple Silicon Macs (M1/M2/M3/M4)
• Issue: Memory was incorrectly reported as ~0.04 GB instead of actual ~40+ GB available
• Root cause: Wrong page size assumption (4,096 vs actual 16,384 bytes on Apple Silicon)
• Impact: Memory reporting was off by factor of ~1000x

Enhanced Cross-Platform Memory Robustness

• macOS: Dynamic page size detection with safe fallbacks
• macOS: Improved available memory calculation (free + inactive + speculative pages)
• Linux: Already robust - no changes needed
• Windows: Already robust - no changes needed
• Universal: Added psutil fallback for any unsupported platforms

Defensive Programming Improvements

• Safe parsing: All vm_stat parsing now wrapped in try/catch blocks
• Graceful degradation: Multiple fallback levels for missing data
• Error resilience: Handles malformed vm_stat output gracefully
• Future-proof: Won't break with macOS format changes

🔧 Technical Improvements

Memory Calculation Strategy by Platform

• Linux: /proc/meminfo parsing (MemTotal/MemFree) - unchanged, already reliable
• macOS: sysctl hw.memsize + enhanced vm_stat parsing with dynamic page size
• Windows: GlobalMemoryStatusEx API - unchanged, already reliable
• Fallback: psutil.virtual_memory() as universal backup when available

Testing Results

• Before: memory_free: 0.039 GB (❌ wrong by ~1000x factor)
• After: memory_free: 93.096 GB (✅ matches Activity Monitor accurately)

📝 Documentation

• Added INSIGHTS.md: Comprehensive analysis of memory calculation robustness
• Cross-platform strategy: Documented approach for each operating system
• Maintenance notes: Guidelines for future macOS compatibility

Contextuals v0.2.0

🐛 Bug Fixes

• Fixed COMPACT prompt user name truncation: Removed 10-character limit on full names in COMPACT variant
• Corrected benchmark documentation: Updated BENCHMARK.md with actual test results and correct prompt examples
• Updated token counts: Corrected prompt token estimates based on real measurements

📊 Documentation Updates

• Rewritten BENCHMARK.md: Based solely on actual test results from tests/benchmarks
• Updated README.md: Corrected all benchmark scores, model recommendations, and examples
• Accurate empirical testing results: Fixed scores from theoretical to actual measured performance
• Speed paradox documentation: Noted unexpected COMPACT variant performance characteristics

🔧 Technical Improvements

• Version consistency: Updated all version references across codebase
• User-Agent headers: Updated to reflect current version in API calls
• Package metadata: Synchronized version across pyproject.toml and init.py

📦 Installation

# Core package
pip install contextuals==0.2.0

# With benchmarking capabilities
pip install "contextuals[benchmarks]==0.2.0"

# Full installation
pip install "contextuals[full]==0.2.0"

🔗 Links

• PyPI: https://pypi.org/project/contextuals/0.2.0/
• Documentation: https://github.com/lpalbou/Contextuals#readme
• Benchmark Results: https://github.com/lpalbou/Contextuals/blob/main/docs/BENCHMARK.md

Contextuals v0.1.0

Initial release of Contextuals

For more information, please consult the README.md