{"id":32705420,"url":"https://github.com/ongteckwu/pyjamaz","last_synced_at":"2026-05-04T00:34:14.018Z","repository":{"id":321897998,"uuid":"1087515800","full_name":"ongteckwu/pyjamaz","owner":"ongteckwu","description":"High-Performance Image Optimizer for Python, Nodejs, Zig, CLI","archived":false,"fork":false,"pushed_at":"2025-11-01T07:06:37.000Z","size":17300,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-01T09:07:57.749Z","etag":null,"topics":["avi","bindings","cli","cli-tool","cross-platform","f","ffi","image-compression","image-optimization","image-processing","jpeg","nodejs","performance","png","python","typescript","webp","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ongteckwu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-01T04:19:05.000Z","updated_at":"2025-11-01T07:50:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ongteckwu/pyjamaz","commit_stats":null,"previous_names":["ongteckwu/pyjamaz"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ongteckwu/pyjamaz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ongteckwu%2Fpyjamaz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ongteckwu%2Fpyjamaz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ongteckwu%2Fpyjamaz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ongteckwu%2Fpyjamaz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ongteckwu","download_url":"https://codeload.github.com/ongteckwu/pyjamaz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ongteckwu%2Fpyjamaz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32590391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"ssl_error","status_checked_at":"2026-05-03T22:09:10.534Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["avi","bindings","cli","cli-tool","cross-platform","f","ffi","image-compression","image-optimization","image-processing","jpeg","nodejs","performance","png","python","typescript","webp","zig"],"created_at":"2025-11-02T01:01:45.666Z","updated_at":"2026-05-04T00:34:14.008Z","avatar_url":"https://github.com/ongteckwu.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pyjamaz - High-Performance Image Optimizer for Nodejs, Python, CLI\n\n**Blazing-fast CLI tool for optimizing images with perceptual quality guarantees. Built with Zig using Tiger Style methodology.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Zig](https://img.shields.io/badge/Zig-0.15+-orange.svg)](https://ziglang.org/)\n[![Tests](https://img.shields.io/badge/Tests-73%2F73_passing-brightgreen)]()\n[![Coverage](https://img.shields.io/badge/Conformance-93%25-green)](docs/TEST_SUITES.md)\n\n---\n\n## 🎯 Why Pyjamaz?\n\n- **🚀 Blazing Fast**: 50-100ms per image with parallel encoding, 15-20x faster with caching\n- **💾 Intelligent Caching**: Content-addressed cache for instant repeated optimizations\n- **🧪 Battle-Tested**: 73/73 unit tests, 196/211 conformance tests (15 skipped), **0 memory leaks**\n- **📊 Smart**: Automatic format selection (JPEG, PNG, WebP, AVIF) with perceptual quality metrics\n- **🔒 Safe**: Never makes files larger - original file always included as baseline\n- **⚡ Efficient**: Memory-optimized processing (no temp files)\n- **🐍 Python Bindings**: Production-ready Python API with automatic memory management\n- **📘 Node.js Bindings**: TypeScript-first API with full type safety and IntelliSense\n- **🐯 Tiger Style**: Safety-first methodology with 2+ assertions per function\n\n---\n\n## 📈 Impressive Stats\n\n| Metric               | Result                                               |\n| -------------------- | ---------------------------------------------------- |\n| **Test Coverage**    | 73/73 unit tests (100%), 196/211 conformance (93%)   |\n| **Memory Safety**    | 0 leaks detected (verified with testing.allocator)   |\n| **Performance**      | 50-100ms per image (5x better than 500ms target)     |\n| **Parallel Speedup** | 1.2-1.4x faster with 4 cores                         |\n| **Compression**      | 87.4% average size reduction (12.6% of original)     |\n| **Regressions**      | 0% - original file baseline prevents size increases  |\n| **Formats**          | 4 (JPEG, PNG, WebP, AVIF)                            |\n| **Metrics**          | 2 perceptual (DSSIM, SSIMULACRA2) + size constraints |\n\n---\n\n## 🚀 Quick Start\n\n### Installation\n\n**From npm** (Node.js):\n\n```bash\nnpm install pyjamaz\n```\n\n**From Homebrew** (coming soon):\n\n```bash\nbrew install pyjamaz\n```\n\n**From Source**:\n\n```bash\n# Install dependencies (macOS)\nbrew install vips jpeg-turbo dssim\n\n# Build\ngit clone https://github.com/yourusername/pyjamaz.git\ncd pyjamaz\nzig build\n\n# Run\n./zig-out/bin/pyjamaz input.jpg -o output.jpg --max-bytes 100000\n```\n\n### Basic CLI Usage\n\n```bash\n# Optimize single image with size constraint\npyjamaz input.jpg -o output.jpg --max-bytes 100000\n\n# Optimize with quality constraint (SSIMULACRA2)\npyjamaz input.png -o output.webp --max-diff 0.002 --metric ssimulacra2\n\n# Batch optimize directory\npyjamaz src/ -o optimized/ --max-bytes 50000\n\n# Generate JSON manifest\npyjamaz input.jpg --manifest results.jsonl\n\n# Use caching for 15-20x speedup\npyjamaz input.jpg --max-bytes 100000\n# Second run: instant cache hit! ⚡\n\n# Custom cache settings\npyjamaz input.jpg --cache-dir /tmp/cache --cache-max-size 2147483648\n```\n\n### Node.js Bindings Usage\n\nPyjamaz can also be used from Node.js with full TypeScript support:\n\n```typescript\nimport pyjamaz from \"pyjamaz\";\n\n// Optimize with size constraint\nconst result = await pyjamaz.optimizeImage(\"input.jpg\", {\n  maxBytes: 100_000,\n});\n\nif (result.passed) {\n  await result.save(\"output.jpg\");\n  console.log(`Optimized to ${result.size} bytes`);\n}\n```\n\n**Features**:\n\n- TypeScript-first design with full type safety\n- Both sync and async APIs\n- Automatic memory management\n- Full caching support (15-20x speedup)\n- Express/Fastify integration examples\n\n**Installation**:\n\n```bash\n# Install Node.js bindings\ncd bindings/nodejs\nnpm install\nnpm run build\n\n# Run examples\nnpm run build \u0026\u0026 node dist/examples/basic.js\nnpx ts-node examples/basic.ts\n```\n\n**Complete documentation**: See [Node.js API Reference](docs/NODEJS_API.md) for detailed usage, examples, and integration guides.\n\n### Python Bindings Usage [Coming Soon]\n\nPyjamaz can also be used as a Python library for programmatic image optimization:\n\n```python\nimport pyjamaz\n\n# Optimize with size constraint\nresult = pyjamaz.optimize_image(\n    'input.jpg',\n    max_bytes=100_000,  # 100KB max\n)\n\nif result.passed:\n    result.save('output.jpg')\n    print(f\"Optimized to {result.size:,} bytes\")\n```\n\n**Features**:\n\n- Automatic memory management (no manual cleanup)\n- Full caching support (15-20x speedup)\n- Quality constraints with perceptual metrics\n- Format selection and detection\n- Batch processing support\n\n**Installation**:\n\n```bash\n# Install from PyPI\nuv pip install pyjamaz-optimizer\n\n# Or install from source\ncd bindings/python\nuv pip install -e .\n\n# Run examples\nuv run python examples/basic.py\nuv run python examples/batch.py\n```\n\n**Complete documentation**: See [Python API Reference](docs/PYTHON_API.md) for detailed usage, examples, and integration guides.\n\n---\n\n## ✨ Features\n\n### Language Bindings\n\n- **Python**: Production-ready bindings with automatic memory management\n\n  - Pythonic API with type hints\n  - Full caching support\n  - Zero external dependencies (uses stdlib ctypes)\n  - Comprehensive test suite\n  - See [Python API Documentation](docs/PYTHON_API.md)\n\n- **Node.js**: TypeScript-first bindings with full type safety\n  - TypeScript-first design with IntelliSense\n  - Both sync and async APIs\n  - Full caching support\n  - Express/Fastify integration\n  - 30+ comprehensive tests (TS + JS)\n  - See [Node.js API Documentation](docs/NODEJS_API.md)\n\n### Multi-Format Support\n\n- **JPEG**: Via libjpeg-turbo (fast, widely supported)\n- **PNG**: Via libpng (lossless)\n- **WebP**: Modern format with excellent compression (80-90% reduction)\n- **AVIF**: Next-gen format (experimental support via libvips)\n\n**Note**: TIFF format is not supported. Pyjamaz focuses exclusively on web image formats. To optimize TIFF files, convert them to PNG first using ImageMagick or similar tools.\n\n### Perceptual Quality Metrics\n\n- **DSSIM**: Structural dissimilarity (FFI to libdssim)\n- **SSIMULACRA2**: Advanced perceptual metric (native Zig via fssimu2)\n- **None**: Fast mode without quality checks (`--metric none`)\n\n### Smart Optimization\n\n- **Automatic Format Selection**: Tries all formats, picks the smallest\n- **Original File Baseline**: Never makes files larger (100% regression-free)\n- **Binary Search**: Automatic quality tuning for size targets\n- **Dual Constraints**: Size limits + perceptual quality guarantees\n\n### Intelligent Caching 💾\n\n**15-20x speedup** on repeated optimizations with content-addressed caching:\n\n- Cache key computed from Blake3 hash of (input bytes + optimization options)\n- Same input + same options = instant cache hit\n- Different options = different cache entries (no collisions)\n- LRU eviction policy with configurable size limit (default 1GB)\n\n**Cache location**:\n\n- Linux/macOS: `~/.cache/pyjamaz/` or `$XDG_CACHE_HOME/pyjamaz/`\n- Windows: `%LOCALAPPDATA%\\pyjamaz\\cache\\`\n\n**Cache management**:\n\n```bash\n# View cache size\ndu -sh ~/.cache/pyjamaz\n\n# Clear cache manually\nrm -rf ~/.cache/pyjamaz\n\n# Cache will auto-evict oldest entries when limit reached\n```\n\n### Advanced Capabilities\n\n- **Transform Operations**:\n  - Auto-sharpen via libvips (`--sharpen auto`)\n  - Alpha flattening with custom background color (`--flatten #FFFFFF`)\n  - EXIF auto-rotation (automatic)\n- **Batch Processing**: Optimize entire directories\n- **Manifest Generation**: JSONL output with optimization metrics\n- **Verbose Logging**: 3 levels (`-v`, `-vv`, `-vvv`)\n- **Exit Codes**: Detailed status (0=success, 1=failed, 10-14=errors)\n\n---\n\n## 📊 Performance Benchmarks\n\n### Optimization Speed\n\n**Platform**: Apple M1 Pro, macOS 15.0, libvips 8.17.0\n\n| Image Size | Sequential | Parallel (4 cores) | Speedup | With Cache |\n| ---------- | ---------- | ------------------ | ------: | ---------: |\n| 100KB PNG  | 80ms       | 67ms               |    1.2x |        5ms |\n| 500KB JPEG | 120ms      | 100ms              |    1.2x |        7ms |\n| 2MB PNG    | 200ms      | 143ms              |    1.4x |       10ms |\n\n**Result**: 5x faster than MVP target (500ms) ✅\n\n### Compression Ratios\n\n**Conformance Test Results** (211 images):\n\n| Test Suite   | Pass Rate         | Avg Compression                         | Notes                          |\n| ------------ | ----------------- | --------------------------------------- | ------------------------------ |\n| Kodak        | 24/24 (100%)      | 9.3% of original                        | Photographic images            |\n| PNGSuite     | 162/176 (92%)     | High reduction                          | 14 intentionally corrupt files |\n| WebP Gallery | 5/5 (100%)        | No regression                           | Already optimal                |\n| TestImages   | 2/3 (67%)         | 15.5% of original                       | 1 TIFF skipped (not supported) |\n| **Overall**  | **196/211 (93%)** | **12.6% of original (87.4% reduction)** | **15 correctly skipped**       |\n\n### Memory Safety\n\n- **Zero leaks** detected across 73 unit tests\n- Verified with Zig's `testing.allocator`\n- All allocations tracked and freed properly\n\n---\n\n## 🏗️ Architecture\n\n### Optimization Pipeline\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 1. Decode \u0026 Normalize (libvips)                        │\n│    • Load from disk or memory buffer                   │\n│    • Auto-rotate via EXIF metadata                     │\n│    • Convert to sRGB color space                       │\n│    • Format detection from magic numbers               │\n└─────────────────────────────────────────────────────────┘\n                          ↓\n┌─────────────────────────────────────────────────────────┐\n│ 2. Cache Lookup (Blake3 hash)                          │\n│    • Compute key from (input + options)                │\n│    • Check cache for existing result                   │\n│    • Return if cache hit (15-20x faster!)              │\n└─────────────────────────────────────────────────────────┘\n                          ↓\n┌─────────────────────────────────────────────────────────┐\n│ 3. Generate Candidates (Parallel)                      │\n│    Thread 1: AVIF encoding   ─┐                        │\n│    Thread 2: WebP encoding   ─┼──→ Candidate Pool      │\n│    Thread 3: JPEG encoding   ─┤                        │\n│    Thread 4: PNG encoding    ─┘                        │\n│    PLUS: Original file (baseline)                      │\n└─────────────────────────────────────────────────────────┘\n                          ↓\n┌─────────────────────────────────────────────────────────┐\n│ 4. Score Candidates (Perceptual Metrics)               │\n│    • Calculate DSSIM or SSIMULACRA2 diff               │\n│    • Filter: diff_score ≤ max_diff                     │\n│    • Filter: file_size ≤ max_bytes                     │\n│    • Keep only candidates passing all constraints      │\n└─────────────────────────────────────────────────────────┘\n                          ↓\n┌─────────────────────────────────────────────────────────┐\n│ 5. Select Best Candidate                               │\n│    • Pick smallest passing candidate                   │\n│    • Tiebreak by format preference                     │\n│    • Cache result for future use                       │\n└─────────────────────────────────────────────────────────┘\n                          ↓\n┌─────────────────────────────────────────────────────────┐\n│ 6. Output                                               │\n│    • Write optimized file                              │\n│    • Generate JSONL manifest (optional)                │\n│    • Return result with timing metrics                 │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Core Modules\n\n```\npyjamaz/\n├── src/\n│   ├── optimizer.zig              # Core optimization pipeline\n│   ├── cache.zig                  # Content-addressed caching (680 LOC)\n│   ├── vips.zig                   # libvips FFI bindings\n│   ├── codecs.zig                 # Multi-format encoding\n│   ├── image_ops.zig              # Image operations\n│   ├── search.zig                 # Binary search for quality\n│   ├── metrics.zig                # Perceptual quality metrics\n│   │   ├── dssim.zig              # DSSIM FFI bindings\n│   │   └── ssimulacra2.zig        # SSIMULACRA2 native impl\n│   ├── cli.zig                    # Command-line interface\n│   └── test/                      # Test suites\n│       ├── unit/                  # 73 unit tests\n│       ├── integration/           # Integration tests\n│       └── benchmark/             # Performance benchmarks\n├── testdata/                      # 211 conformance test images\n└── docs/                          # Comprehensive documentation\n```\n\n---\n\n## 🧪 Testing\n\n### Test Coverage\n\n| Category              | Count | Pass Rate     | Status         |\n| --------------------- | ----- | ------------- | -------------- |\n| **Unit Tests**        | 73    | 100% (73/73)  | ✅ All passing |\n| **Conformance Tests** | 211   | 93% (196/211) | ✅ Excellent   |\n| **Memory Leak Tests** | All   | 0 leaks       | ✅ Clean       |\n| **Integration Tests** | 8     | 100% (8/8)    | ✅ All passing |\n\n**Skipped Tests**:\n\n- 14 PNGSuite files (intentionally malformed test files: xc*, xd*, xs*, xh*, xlf\\*)\n- 1 TIFF file (not supported - web formats only)\n\n### Test Suites\n\n- **PNGSuite**: 176 PNG files (162 valid + 14 intentionally corrupt for robustness testing)\n- **Kodak**: 24 photographic test images (industry standard)\n- **WebP**: 5 WebP gallery images\n- **Samples**: 3 reference images\n- **TestImages**: 3 files (2 PNG + 1 TIFF skipped)\n- **Total**: 211 conformance test images (196 passing, 15 correctly skipped)\n\n### Run Tests\n\n```bash\n# All unit tests\nzig build test\n\n# Conformance tests (211 images)\nzig build conformance                    # Fast mode (~3s, size checks only)\nzig build conformance -Denable-dssim     # With DSSIM quality checks (~15-20s)\n\n# Integration tests\nzig build test-integration\n\n# Memory tests (CI/CD recommended)\nzig build memory-test              # Zig memory tests (~1 min)\nzig build memory-test-zig          # Same as above\n\n# Benchmarks\nzig build benchmark\n\n# Specific module\nzig build test -Dtest-filter=optimizer\n```\n\n#### Conformance Test Modes\n\n**Fast Mode** (default, ~3s):\n\n```bash\nzig build conformance\n```\n\n- Verifies: Format support, compression ratio, no crashes\n- DSSIM values: 0.0000 (not computed for speed)\n- Use for: Quick iteration, CI/CD, format verification\n\n**DSSIM Mode** (thorough, ~15-20s):\n\n```bash\nzig build conformance -Denable-dssim\n```\n\n- Verifies: All of the above + perceptual quality with DSSIM metric\n- DSSIM values: Real values (e.g., 0.0020, 0.0005, 0.0003)\n- Quality threshold: 0.01 (1% max perceptual difference)\n- Use for: Release testing, quality regression detection, codec validation\n\n**Why 15 Tests are Skipped**:\n\n- **14 PNGSuite files**: Intentionally malformed test files designed to test decoder robustness\n  - `xc*`: Invalid color type\n  - `xd*`: Invalid bit depth\n  - `xs*`: Invalid PNG signature\n  - `xh*`: Invalid header\n  - `xlf*`: Invalid chunk length\n- **1 TIFF file**: Not supported (pyjamaz focuses on web image formats only)\n\nThese files are **correctly skipped** - attempting to optimize corrupt/unsupported files would be an error.\n\n#### Manual Memory Tests (Node.js \u0026 Python)\n\nThe Node.js and Python memory tests are available but require manual setup:\n\n**Node.js Memory Tests:**\n\n```bash\n# Prerequisites\nzig build                          # Build library first\ncd bindings/nodejs\nnpm install                        # If not done already\n\n# Run tests\nnode --expose-gc tests/memory/gc_verification_test.js\nnode tests/memory/ffi_memory_test.js\nnode tests/memory/error_recovery_test.js\nnode tests/memory/buffer_memory_test.js\n```\n\n**Python Memory Tests:**\n\n```bash\n# Prerequisites\nzig build                          # Build library first\nuv pip install psutil               # Optional: for better memory tracking\n\n# Run tests\ncd bindings/python\nuv run python tests/memory/gc_verification_test.py\nuv run python tests/memory/ctypes_memory_test.py\nuv run python tests/memory/error_recovery_test.py\nuv run python tests/memory/buffer_memory_test.py\n```\n\n**Expected Results:**\n\n- All tests should report \"TEST PASSED\"\n- Zero memory leaks detected\n- Colored output showing progress\n\n**Note:** If tests fail with module not found errors, set the library path:\n\n```bash\nexport PYJAMAZ_LIB_PATH=/path/to/pyjamaz/zig-out/lib/libpyjamaz.dylib\n```\n\nSee [docs/MEMORY_TESTS.md](docs/MEMORY_TESTS.md) for detailed troubleshooting.\n\n````\n---\n\n## 📚 Documentation\n\n### Guides\n\n- **[TODO Roadmap](docs/TODO.md)** - Development roadmap and milestones\n- **[Contributing Guide](docs/CONTRIBUTING.md)** - How to contribute\n- **[Tiger Style Guide](docs/TIGER_STYLE_APPLICATION.md)** - Coding standards\n- **[Quick Start](docs/QUICKSTART.md)** - Getting started guide\n\n### API Documentation\n\n- **[Python API Reference](docs/PYTHON_API.md)** - Complete Python bindings documentation\n\n  - Installation and setup\n  - API reference with all parameters\n  - Usage examples (basic, batch, Flask, FastAPI)\n  - Performance tips and troubleshooting\n\n- **[Node.js API Reference](docs/NODEJS_API.md)** - Complete Node.js/TypeScript bindings documentation\n  - Installation and setup\n  - TypeScript-first API with full type definitions\n  - Usage examples (async/sync, batch, Express, Fastify)\n  - Integration guides and troubleshooting\n\n### Implementation Details\n\n- **[Performance Optimizations](docs/OPTIMIZATIONS.md)** - Complete optimization guide\n- **[Perceptual Metrics Design](docs/PERCEPTUAL_METRICS_DESIGN.md)** - DSSIM \u0026 SSIMULACRA2\n- **[Parallel Optimization](docs/PARALLEL_OPTIMIZATION.md)** - Thread pool design\n- **[Test Suites](docs/TEST_SUITES.md)** - Conformance test tracking\n- **[RFC Documents](docs/RFC.md)** - Design decisions\n\n---\n\n## 🐯 Tiger Style Methodology\n\nPyjamaz follows [Tiger Style](https://github.com/tigerbeetle/tigerbeetle/blob/main/docs/TIGER_STYLE.md) for safety and predictability:\n\n### 1. Safety First ✅\n\n```zig\npub fn optimizeImage(allocator: Allocator, job: OptimizationJob) !OptimizationResult {\n    // Pre-conditions (4 assertions)\n    std.debug.assert(job.formats.len \u003e 0);\n    std.debug.assert(job.concurrency \u003e 0);\n    std.debug.assert(job.input_path.len \u003e 0);\n    std.debug.assert(job.output_path.len \u003e 0);\n    // ... rest of function\n}\n```\n\n- **2+ assertions per function**: Validate inputs, outputs, invariants\n- **Bounded loops**: No `while(true)`, explicit MAX constants\n- **Explicit error handling**: `try` or explicit `catch`, never silent failures\n\n### 2. Predictable Performance ✅\n\n```zig\nconst MAX_ITERATIONS: u8 = 7; // log2(100 quality levels) ≈ 6.6\nwhile (iteration \u003c MAX_ITERATIONS and q_min \u003c= q_max) : (iteration += 1) {\n    // Binary search converges in ≤7 iterations guaranteed\n}\nstd.debug.assert(iteration \u003c= MAX_ITERATIONS);\n```\n\n- **Bounded operations**: All loops and allocations have explicit limits\n- **Back-of-envelope calculations**: Performance claims documented\n- **Static allocation**: Prefer stack over heap where possible\n\n### 3. Developer Experience ✅\n\n- **Functions ≤70 lines**: Easy to understand and review\n- **Clear naming**: `binarySearchQuality` not `binSearch`\n- **Documentation**: Explain WHY, not WHAT\n\n### 4. Minimal Dependencies ✅\n\n- **Only Zig stdlib + system libraries**: libvips, libjpeg-turbo, libdssim\n- **Pure Zig implementation**: Except for codec/metric system libraries\n- **Justification**: System libraries are battle-tested and industry-standard\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! Pyjamaz is built to be contributor-friendly.\n\n### Quick Start\n\n1. **Find a task**: Check [docs/TODO.md](docs/TODO.md)\n2. **Follow Tiger Style**: See [docs/TIGER_STYLE_APPLICATION.md](docs/TIGER_STYLE_APPLICATION.md)\n3. **Write tests**: \u003e80% coverage, use `testing.allocator`\n4. **Format \u0026 test**: `zig fmt src/` then `zig build test`\n\n### Development Workflow\n\n```bash\n# Fork and clone\ngit clone https://github.com/yourusername/pyjamaz.git\ncd pyjamaz\n\n# Create feature branch\ngit checkout -b feature/my-feature\n\n# Make changes (follow Tiger Style)\n# - 2+ assertions per function\n# - Functions ≤70 lines\n# - Bounded loops with MAX constants\n\n# Write tests\n# src/test/unit/my_module_test.zig\n\n# Run checks\nzig build test\nzig build conformance\nzig fmt src/\n\n# Commit and push\ngit commit -m \"feat: Add awesome feature\n\n- Implemented X with Y approach\n- Added Z tests\n- Performance: \u003c100ms\"\n\ngit push origin feature/my-feature\n```\n\nSee [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for detailed guidelines.\n\n---\n\n## 🚀 Roadmap\n\nSee [docs/TODO.md](docs/TODO.md) for the complete development roadmap.\n\n**Current Focus** (v1.0.0):\n\n- ✅ Core engine stable (73/73 tests passing)\n- ✅ Caching layer (15-20x speedup)\n- ✅ Python bindings complete (automatic memory management, comprehensive tests)\n- ✅ Node.js bindings complete (TypeScript-first, sync/async APIs, 30+ tests)\n- 🔄 Replace libvips with native decoders (2-5x performance improvement)\n- ⏳ Homebrew distribution (`brew install pyjamaz`)\n- ⏳ Production polish (fuzzing, security audit)\n\n**Future** (v1.1.0+):\n\n- Watch mode (re-optimize on file changes)\n- JSON output mode (machine-readable)\n- Progress bars for batch operations\n- Config file support (`.pyjamazrc`)\n\n---\n\n## 🙏 Acknowledgments\n\n- **[Zig Language](https://ziglang.org/)** - Safe, fast systems programming\n- **[TigerBeetle](https://github.com/tigerbeetle/tigerbeetle)** - Tiger Style inspiration\n- **[libvips](https://www.libvips.org/)** - Fast image processing library\n- **[PNGSuite](http://www.schaik.com/pngsuite/)** - Comprehensive PNG test images\n- **[fssimu2](https://github.com/rust-av/ssimulacra2)** - SSIMULACRA2 implementation\n\n---\n\n## 📜 License\n\nMIT License - see [LICENSE](./LICENSE) for details.\n\n---\n\n## 🌟 Star History\n\nIf Pyjamaz helps you, please consider giving it a star! ⭐\n\n---\n\n## 📬 Contact\n\n- **Issues**: [GitHub Issues](https://github.com/yourusername/pyjamaz/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/yourusername/pyjamaz/discussions)\n\n---\n\n**Last Updated**: 2025-10-31 (Python \u0026 Node.js bindings complete!)\n**Current Version**: 1.0.0-dev (CLI + Python + Node.js bindings)\n**Status**: Pre-1.0 (core stable, bindings ready, optimizing performance)\n\n🚀 **Happy optimizing!**\n````\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fongteckwu%2Fpyjamaz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fongteckwu%2Fpyjamaz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fongteckwu%2Fpyjamaz/lists"}