[Bug]: Cannot import QScheme from coreai_opt.coreai_utils as documented in coreai_compression.md

[rohith500]

Summary

In docs/src/utils/coreai_compression.md#L92-L97, the official documentation provides an example demonstrating advanced weight quantization:

from coreai_opt.coreai_utils import (
    CompressionGranularity,
    DType,
    QScheme,
    quantize_weights,
)

# --- quantize weights with advanced options ---
compressed_program = quantize_weights(
    coreai_program=coreai_program,
    dtype=DType.FP8_E4M3FN,  # quantize weights to FP8 E4M3FN
    qscheme=QScheme.SYMMETRIC,  # only symmetric is supported for FP8 dtypes
    granularity=CompressionGranularity.PER_BLOCK,  # one scale per block of axes
    block_size=32,  # block size for PER_BLOCK
    weight_num_threshold=2048,  # skip tensors with <= 2048 elements
    scale_dtype=DType.FP8_E8M0FNU,  # store scales in FP8 E8M0FNU format
    in_place=True,  # modify coreai_program in-place
)

However, executing this snippet raises an ImportError:

ImportError: cannot import name 'QScheme' from 'coreai_opt.coreai_utils' (/.../src/coreai_opt/coreai_utils/__init__.py)

---

Root Cause

src/coreai_opt/coreai_utils/common.py defines three core enums used across coreai_utils: DType, QScheme, and CompressionGranularity, with __all__ = ["CompressionGranularity", "DType", "QScheme"].

However, in src/coreai_opt/coreai_utils/__init__.py:

from coreai_opt.coreai_utils.common import CompressionGranularity, DType
from coreai_opt.coreai_utils.passes.weight_palettization import palettize_weights
from coreai_opt.coreai_utils.passes.weight_quantization import quantize_weights
from coreai_opt.coreai_utils.passes.weight_sparsification import sparsify_weights

__all__ = [
    "CompressionGranularity",
    "DType",
    "palettize_weights",
    "quantize_weights",
    "sparsify_weights",
]

CompressionGranularity and DType are re-exported in __all__, but QScheme was inadvertently omitted.

Furthermore, quantize_weights() accepts qscheme: QScheme = QScheme.SYMMETRIC in its function signature, so users invoking quantize_weights need direct access to QScheme alongside DType and CompressionGranularity.

Additionally, because docs/scripts/generate_api_index.py groups APIs by their shallowest package export, omitting QScheme causes an orphaned ### coreai_opt.coreai_utils.common section to be generated containing only QScheme, while DType and CompressionGranularity appear under ## coreai_opt.coreai_utils.

---

Step-by-Step Reproduction

python -c "from coreai_opt.coreai_utils import QScheme"

Actual Output:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
ImportError: cannot import name 'QScheme' from 'coreai_opt.coreai_utils' (/path/to/src/coreai_opt/coreai_utils/__init__.py)

Expected Output:

Successful import with coreai_opt.coreai_utils.QScheme resolving to coreai_opt.coreai_utils.common.QScheme.

---

Proposed Fix

1. In src/coreai_opt/coreai_utils/__init__.py, import and export QScheme:

from coreai_opt.coreai_utils.common import CompressionGranularity, DType, QScheme
...
__all__ = [
    "CompressionGranularity",
    "DType",
    "QScheme",
    "palettize_weights",
    "quantize_weights",
    "sparsify_weights",
]

2. Add a test in tests/coreai_utils/test_exports.py verifying that all expected symbols, including QScheme, are re-exported and accessible directly from coreai_opt.coreai_utils.

3. Re-generate API documentation (python docs/scripts/generate_api_index.py), which cleanly groups all three enums under coreai_opt.coreai_utils.

[rohith500]

Submitted PR #116 to resolve this issue.