feat(zai): add Z.AI provider with tier-aware rate limiting

[Societus]

Summary

Adds Z.AI (Zhipu AI) as a supported LLM provider with plan-aware rate limiting based on subscription tier (Lite/Pro/Max).

Built on top of the Z.AI provider implementation from #74 (thanks @vinit13792), rebased onto latest main with the addition of tier-aware rate limiting and improved retry behavior.

Changes

Z.AI Provider (zai.py)

• Full Z.AI API integration (OpenAI-compatible) with support for GLM-5.1, GLM-5, GLM-5-Turbo, and GLM-4-Flash
• Thinking mode toggle (ZAI_THINKING=enabled|disabled) for GLM-5 family reasoning tokens
• Plan-aware endpoints: ZAI_PLAN=coding|payg maps to the correct base URL
• Tier-aware rate limiting via ZAI_TIER=lite|pro|max environment variable
  • Tier takes precedence over registry-attached default rate limiter
  • Invalid tier raises ValueError with valid options listed
• Improved retry budget: 5 retries with up to 30s backoff (up from 3 retries / 4s) to handle Z.AI load-shedding under concurrent use

Rate Limiter (rate_limiter.py)

• Updated Z.AI default from placeholder (60 RPM / 150K TPM) to conservative 10 RPM / 50K TPM
• Added ZAI_TIER_DEFAULTS with per-tier limits derived from Z.AI support guidance:
  • Lite: 10 RPM / 50K TPM (2-3 concurrent)
  • Pro: 30 RPM / 150K TPM (5-8 concurrent)
  • Max: 60 RPM / 300K TPM (10-15 concurrent)

CLI Helpers (helpers.py)

• ZAI_TIER env var read in both explicit and auto-detect provider resolution paths
• ZAI_BASE_URL for custom endpoint override
• ZAI_PLAN for plan selection

Tests (10 new)

• Tier creation, per-tier limit verification (lite/pro/max)
• Case-insensitive tier matching
• Tier precedence over explicit rate limiter
• Invalid tier error handling
• No-tier / no-limiter edge cases

Configuration

# Required
export ZAI_API_KEY="your-key"

# Optional — defaults to conservative (Lite-equivalent)
export ZAI_TIER="pro"           # lite | pro | max
export ZAI_PLAN="coding"        # coding | payg
export ZAI_THINKING="disabled"  # enabled | disabled
export ZAI_BASE_URL="..."       # override plan-based URL

Rate Limit Context

Z.AI's concurrency limits are dynamic and not published as fixed numbers. The tier defaults above are conservative starting points based on guidance from Z.AI support (April 2026):

• Limits are aggregate across all models (not per-model)
• Advanced models (GLM-5 family) consume 2-3x quota per prompt due to reasoning tokens, so effective concurrency is lower with those models
• Recommended: exponential backoff on 429 errors (already implemented in provider retry logic)

Ref: https://docs.z.ai/devpack/usage-policy

Related

• Builds on provider work from feat: add Z.AI (Zhipu AI) provider support #74 (by @vinit13792)
• Addresses rate-limiting concerns raised in Feature: Add Z.AI (Zhipu AI) provider support #68
• Supersedes the placeholder rate limits noted in PR feat: add Z.AI (Zhipu AI) provider support #74 comments

Test Plan

uv run python -m pytest tests/unit/test_providers/test_zai_provider.py -v
# 32 passed (22 existing + 10 new tier tests)

[Societus]

Superseded by layered PR stack

This monolithic PR has been split into two focused PRs that build on each other:

1. feat: add generic tier-aware rate limiting framework #82 — Generic tier-aware rate limiting framework (provider-agnostic foundation in BaseProvider)
2. feat(zai): adopt tier framework for plan-aware rate limiting #83 — Z.AI adopts the tier framework (Z.AI-specific tier configs, env vars, tests)

The layered approach is cleaner because:

• The generic framework (feat: add generic tier-aware rate limiting framework #82) can be reviewed and merged independently — it adds zero Z.AI-specific code
• Z.AI adoption (feat(zai): adopt tier framework for plan-aware rate limiting #83) is a thin layer that uses the framework, making the integration obvious
• Future providers (MiniMax, etc.) get the framework for free without duplicating tier resolution logic

Both PRs are ready for review with passing tests.