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:

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:

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.

2.8 KiB Raw Blame History