albucore: Instructions file for Codex

Codex AI Development Guidelines for Albucore

This document provides guidelines and conventions for AI assistants (particularly Codex) when working on the Albucore codebase.

Project Overview

Albucore is a high-performance image processing library that provides optimized atomic functions for image manipulation. It serves as the foundation for AlbumentationsX and focuses on:

• Maximum performance through multiple backend implementations (NumPy, OpenCV, custom)
• Supported image dtypes: uint8, float16, and float32 (no float64 image inputs)
• Backend routing is based ONLY on performance — benchmark before choosing. If LUT is slower, don't use it.
• Consistent API across different image types and shapes

Core Documentation

Please familiarize yourself with these key documents:

1. Image Shape Conventions - CRITICAL rules about image shapes

   • All images must have an explicit channel dimension
   • NumPy uses channel-last; Torch CPU uses an explicit channel-first layout
   • Grayscale images use (H, W, 1) or a declared layout with C=1

2. Performance Optimization - Performance best practices

   • LUT operations and float32 dtype management
   • Backend selection strategies
   • Memory layout considerations
   • Benchmarking guidelines

3. Public API - Public operations, explicit root exports, and owning modules

4. PyTorch Optimization - Eager CPU Torch contracts, full-path benchmarks, Tensor/NumPy bridge costs, profiling, allocation, layout, and threading decisions

5. NumKong Performance - NumKong vs OpenCV/NumPy/LUT benchmark tables and methodology

Repo-Local Codex Skills

Repo-specific Codex skills live in .codex/skills/:

• albucore-conventions - Apply when implementing or reviewing image-processing code, tests, shape handling, dtype handling, and backend routing.
• albucore-benchmarks - Apply when adding benchmarks, comparing versions, or documenting benchmark workflow.
• performance-optimization - Apply for every runtime implementation, review, profile, or optimization. It loads docs/performance-optimization.md completely and runs the delete-first, vectorization, grouped-reduction, LUT, RNG, backend, extraction, and explicit-output/alias audit.
• torch-performance-optimization - Apply for every eager CPU-only Torch runtime implementation, review, profile, routing, layout, allocation, threading, or benchmark decision. It loads docs/torch-performance-optimization.md and adds Torch-specific contract, profiler, bridge, and full-path benchmark checks.
• albucore-public-api - Apply when changing exports, documenting API status, or deciding what belongs in package __all__.