> ## Documentation Index
> Fetch the complete documentation index at: https://doc.blueapi.ir/llms.txt
> Use this file to discover all available pages before exploring further.

# Quantization Engine: Precision Reduction for Inference

> QuantizationEngine reduces model weights to FP16, BF16, FP8, INT8, or INT4. This page specifies the decision tree, flowchart, and quality gates.

QuantizationEngine compresses model weights and activations to lower precision formats for faster inference and smaller memory footprints. This page specifies the supported methods, the selection decision tree, and the validation flow that prevents quality regression.

## Supported Methods

| Method | Precision     | Use Case                          | Notes                                                             |
| ------ | ------------- | --------------------------------- | ----------------------------------------------------------------- |
| FP16   | 16-bit float  | General GPU inference             | Widely supported, minimal range loss                              |
| BF16   | 16-bit bfloat | Ampere+ GPUs                      | Wider dynamic range than FP16                                     |
| FP8    | 8-bit float   | Hopper+ GPUs, throughput          | NVIDIA transformer engine support                                 |
| INT8   | 8-bit integer | Edge, CPU, latency-sensitive      | Requires calibration; static or dynamic scaling                   |
| INT4   | 4-bit integer | Maximum compression, memory-bound | Group-wise or block-wise; GPTQ/AWQ style (Engineering assumption) |

<Note>
  FP8 and INT4 support depend on hardware availability and backend implementation. The engine falls back to the nearest supported precision if the target backend cannot execute the chosen format.
</Note>

## Decision Tree

The engine selects a quantization method based on target hardware, latency requirements, memory constraints, and quality tolerance. The decision tree below shows the selection logic.

```mermaid theme={null}
flowchart TD
    START([START]) --> INPUT[INPUT: Model, Target Hardware, Latency Budget, Memory Budget]
    INPUT --> CHECK_FP8{Target supports FP8?}
    CHECK_FP8 -->|YES| CHECK_LATENCY{Latency critical?}
    CHECK_FP8 -->|NO| CHECK_BF16{Target supports BF16?}
    CHECK_LATENCY -->|YES| SELECT_FP8[SELECT FP8]
    CHECK_LATENCY -->|NO| CHECK_BF16
    CHECK_BF16 -->|YES| CHECK_MEMORY{Memory < 50% of FP16?}
    CHECK_BF16 -->|NO| SELECT_FP16[SELECT FP16]
    CHECK_MEMORY -->|YES| SELECT_INT8[SELECT INT8]
    CHECK_MEMORY -->|NO| SELECT_BF16[SELECT BF16]
    SELECT_FP8 --> OUTPUT
    SELECT_FP16 --> OUTPUT
    SELECT_BF16 --> OUTPUT
    SELECT_INT8 --> CHECK_INT4{Memory < 25% of FP16?}
    CHECK_INT4 -->|YES| SELECT_INT4[SELECT INT4]
    CHECK_INT4 -->|NO| OUTPUT
    SELECT_INT4 --> OUTPUT
    OUTPUT[OUTPUT: Selected Method + Config] --> END([END])
```

## Quantization Flowchart

Every quantization job follows the same pipeline. The flowchart below shows the full lifecycle from model input to acceptance or rejection.

```mermaid theme={null}
flowchart TD
    START([START]) --> INPUT[INPUT: Model, Method, Config, Thresholds]
    INPUT --> PREBENCH[Pre-quant Benchmark]
    PREBENCH --> SELECT[Method Selection]
    SELECT --> QUANT[Quantize Weights + Activations]
    QUANT --> INTEGRITY[Integrity Check: Hash + Structure Validation]
    INTEGRITY -->|FAIL| REJECT1[Reject / Retry]
    INTEGRITY -->|PASS| POSTBENCH[Post-quant Benchmark]
    POSTBENCH --> REGRESS{Quality Regression?}
    REGRESS -->|YES| REJECT2[Reject / Retry]
    REGRESS -->|NO| ACCEPT[Accept: Store Quantized Artifact]
    REJECT1 --> END_FAIL([END: FAIL])
    REJECT2 --> END_FAIL
    ACCEPT --> END_PASS([END: PASS])
```

## Quality Gates

Pre-quant and post-quant benchmarks run on the same dataset split to ensure comparability. The engine computes perplexity, accuracy, and task-specific metrics. A regression gate compares post-quant results against pre-quant baselines and against the thresholds defined in OQ-006.

| Gate                  | Metric                                        | Action on Failure                      |
| --------------------- | --------------------------------------------- | -------------------------------------- |
| Integrity Check       | SHA-256 hash match, layer count, tensor shape | Reject and retry with same config      |
| Perplexity Regression | Perplexity delta > OQ-006 threshold           | Reject and retry with higher precision |
| Accuracy Regression   | Accuracy delta > OQ-006 threshold             | Reject and retry with higher precision |

<Warning>
  Threshold values in OQ-006 are placeholders pending experimental calibration. Do not deploy quantized models in production until thresholds are finalized.
</Warning>

## Retry Policy

On rejection, the engine retries with the next higher precision in the hierarchy: INT4 → INT8 → FP8 → BF16 → FP16. After three retries, the job fails and the model remains in its original precision. The retry count and final state are logged to [ExperimentTracker](/tracking/experiment-tracking).

## Integration

QuantizationEngine is invoked by [DeploymentManager](/deployment/deployment-specification) before staging and by [Offline Deployment](/deployment/offline-deployment) when building secure transfer packages. It reads from [ArtifactStore](/tracking/artifact-registry) and writes quantized artifacts back to the same store with a new version tag.