# grok2api Model Patching Pattern

When adding a new Grok model to the grok2api codebase, 6 files across 3 layers must be updated.

## Files to Patch

### Layer 1: Control Plane — Model Registry

**`app/control/model/enums.py`**
- Add new `ModeId` enum value (e.g., `GROK_4_6 = 5`)
- Add mapping in `to_api_str()` method
- Add to `ALL_MODES_FULL` tuple

**`app/control/model/registry.py`**
- Add `ModelSpec` entries for the new model and its variants
- Example pattern:
```python
ModelSpec("grok-4.6",           ModeId.GROK_4_6, Tier.SUPER, Capability.CHAT, True, "Grok 4.6"),
ModelSpec("grok-4.6-super",     ModeId.GROK_4_6, Tier.SUPER, Capability.CHAT, True, "Grok 4.6 Super"),
ModelSpec("grok-4.6-heavy",     ModeId.GROK_4_6, Tier.HEAVY, Capability.CHAT, True, "Grok 4.6 Heavy"),
ModelSpec("grok-4.6-best",      ModeId.GROK_4_6, Tier.SUPER, Capability.CHAT, True, "Grok 4.6 Best", prefer_best=True),
```

### Layer 2: Control Plane — Account Models

**`app/control/account/models.py`**
- Add `grok_4_6: QuotaWindow | None = None` to `AccountQuotaSet`
- Add `mode_id == 5` case in `get()` method
- Add `mode_id == 5` case in `set()` method
- Add `grok_4_6` to `to_dict()` and `from_dict()`

**`app/control/account/commands.py`**
- Add `quota_grok_4_6: dict[str, Any] | None = None` to `AccountPatch`

### Layer 3: Data Plane — Runtime Tables

**`app/dataplane/shared/enums.py`**
- Add `GROK_4_6 = 5` to `ModeId`
- Add to `ALL_MODE_IDS` tuple

**`app/dataplane/account/table.py`**
- Add `quota_grok_4_6_by_idx`, `total_grok_4_6_by_idx`, `window_grok_4_6_by_idx`, `reset_grok_4_6_at_by_idx` column arrays
- Update `_quota_col()`, `_reset_col()`, `_total_col()`, `_window_col()` to handle `mode_id == 5`
- Update `_append_slot()` signature and body with `grok_4_6` parameters
- Update `_update_slot()` signature and body with `grok_4_6` parameters

## Verification

After patching, run syntax check:
```bash
cd C:\Users\User\grok2api\grok2api
python -c "
import ast, sys
for f in ['app/control/model/enums.py','app/control/model/registry.py',
          'app/control/account/models.py','app/control/account/commands.py',
          'app/dataplane/shared/enums.py','app/dataplane/account/table.py']:
    ast.parse(open(f).read()); print(f'OK: {f}')
"
```

## Pitfalls

- **Columnar arrays**: the table.py uses typed `array.array` columns. Each new mode needs 4 new columns (quota, total, window, reset). The `_append_slot` and `_update_slot` methods have long parameter lists that must match exactly.
- **Mode ID consistency**: the control-plane `ModeId` and data-plane `ModeId` must have the same integer values. The data-plane enum is a separate copy in `dataplane/shared/enums.py`.
- **The protocol layer (`xai_chat.py`) uses `mode_id.to_api_str()` generically** — no changes needed there if the mode_id mapping is correct.