google-ai-edge/ai-edge-quantizer/auto-quant

Agent Contribution Guide: AI Edge Quantizer Recipe Exploration

Welcome, AI Agent! This skill governs how you autonomously explore and generate the optimal selective quantization recipe for any given LiteRT FlatBuffer (.tflite) model using the AI Edge Quantizer (AEQ) framework. Strict adherence to these protocols ensures code is high-quality, memory safe, and meets verification protocols.

Your goal is to build an iterative search loop in Python that actively interrogates the baseline model for numerical degradation, updates the recipe on the fly to protect highly sensitive tensors, and produces a bounding-box of Pareto-optimal models for the user.

Skill Index

Leverage these project-specific skill guides to navigate and execute tasks effectively.

Core guides (read ALL of these before proceeding):

Pluggable task evaluation family (read ONLY the file matching the model's modality):

Conditional guides (read when applicable):

Phase 0: Understand the Framework and Classify the Model

Before beginning, explicitly use specific file reading tools to read all core guides in the Skill Index, plus the ONE task evaluation guide matching the model's modality, plus any applicable conditional guides.

Then, before writing any plan:

1. Classify the modality (segmentation, LLM, classification, embedding,

audio, regression) from the model's signatures, I/O tensor shapes, and the user's description. This selects your metrics (error_metric_selection.md) and evaluation family.

1. Classify the scale tier (S/M/L per model_scale_tiers.md) from the

float model file size and signature count. This selects your search budget, batching strategy, and protection-mechanism priority.

1. Implementation Plan Guidelines

Because complex selective quantization tasks can cause context loss during execution, your first action MUST be to draft a highly explicit, self-contained Implementation Plan. Since you will follow this plan closely, you must bake all necessary context directly into it.

You MUST output this plan as an artifact file (e.g. implementation_plan.md, using your file-writing tool). In interactive sessions, HALT after writing the plan and explicitly ask the user for permission to proceed before you make any code edits or run any loops. If the user has already provided explicit bounds AND explicitly requested unattended/autonomous execution (e.g. a CI pipeline), you may proceed without halting, but the plan artifact is still mandatory. You must strictly follow this plan once approved.

Your printed plan must contain:

Step 1: Context & Role Declaration

• Role Judgment: Declare your role (Contributor, Maintainer, or Reviewer).
• Model Classification: State the detected modality, the scale tier, and

the resulting metric selections and search budgets.

• Context Summary: Explicitly write out a 2-3 sentence summary of the

specific constraints you read from the skill docs. You MUST explicitly state that your artifact names will obey the strict rules from file_naming.md and explicitly confirm you will produce a Pareto visualization per pareto_curve_plotting.md.

Step 2: Technical Design & File List

• Target Files: Explicitly list all files you plan to create or modify.

Please adhere strictly to the output_report.md requirements.

• Optimization Constraints: Briefly outline how you will handle target

file size bounds, acceptable error thresholds across MULTIPLE metrics, and generic regex targeting to prevent data leakage.

Step 3: Experiment Harness Architecture

• Metric Selection: Infer from the float model what metrics you should use

for validation following the guidelines of error_metric_selection.md, including the modality-appropriate stopping metric.

• Experiment Blueprint: Explicitly outline your script structure focusing

on proper API sequential updates, memory-safe Quantizer instantiation per permutation, strictly sequential qt.validate() calls (one validation at a time), explicit garbage collection (import gc; gc.collect()), and selecting layer candidates. Most importantly, explicitly confirm you are implementing the stringent Two-Phase loop mandated by `experiment_runner.md` (Phase 1: Freezing protection set, Phase 2: Iterative Greedy INT4 squashing sorted by robustness, batched per your scale tier). Do not hallucinate trial-and-error hacks.

• Budget Declaration: State the per-tier validation cap and sample count

you will operate under (from model_scale_tiers.md).

Step 4: Verification Plan

• Review Hand-off: Document your explicit commitment to run the Two-Pass

Review Loop (see "Agent Verification Protocol" below) on your execution script before you present the final report. If your harness supports launching subagents, commit to delegating the review to a reviewer subagent; otherwise commit to performing the structured self-review pass against the Reviewer checklist. ONLY start the review after you think you're done with the quantization exploration process.

Step 5: Post-Execution Walkthrough

• Acknowledge that the final response will adhere to the Post-Execution

Walkthrough Guidelines (below).

Phase 1: Setup & Bounding Box

1. Ask the User for Bounds: If the user did not specify, explicitly ask for

either their Minimum Model Compression Ratio / Model Size OR their Max Tolerable Error Bound. Our objective is to find either the best quality model given the minimum compression ratio or the smallest model given the max tolerable error bound.

1. Acquire Verification Preprocessing: In order to use qt.validate(), you

need numpy tensor inputs matching the model's signature(s). You may copy the input processing logic from existing manual human scripts in the directory (for example processing.py), or construct tokenized prompts for LLMs per llm_eval.md.

• CRITICAL CONSTRAINT (NO LEAKAGE): You MUST NOT copy the human's

manual selective recipe adjustments from existing sources or tutorials to blindly inject layer names. You must discover which layers to protect dynamically based on your own validation metric parsing! This equally applies to the empirical anecdotes and example values inside these skill guides: treat them as unverified priors that motivate WHERE to look, never as pre-validated protection lists or expected metric values. Every protection you commit must be justified by a measurement from YOUR current run.

• Single-source-input warning: If the user provides only ONE test

input, deterministic augmentations of it are acceptable for the search loop, but the resulting recipe may be mildly overfit to that input. You MUST state this limitation explicitly in the final report and recommend re-validating the chosen profiles on a small held-out set before production use.

1. Effort & Sizing Logic: The user's size bounds represent a limit, NOT a

target to match exactly. You are authorized to return models that are smaller than requested! The primary goal is to maximize accuracy (or the target metric) while guaranteeing the model is small enough. If you can make it even smaller while retaining acceptable accuracy, do so. Never artificially inflate the model just to hit a bound. Try multiple iterations until you have found the best possible quantization recipe, within the validation budget of your scale tier.

Phase 2: Building the Iteration Harness

Do not try to guess the recipe blindly or write concurrent sweeps. You must construct a dedicated, repeatable Python evaluation script (e.g. explore_aeq_model.py) that operates on ONE recipe at a time. Do not run parallel configurations or concurrent validations.