Route Catalog Snapshot Contracts for OpenAI-Compatible SDK CI (September 2026)

[chawkian]

An OpenAI-compatible SDK can make model switching feel simple, but CI still needs to know what it is testing against. If the route catalog changes between two releases, a passing integration test may only prove that the HTTP shape still works. It may not prove that the same model, pricing version, cache policy, or account group was used.

For aiwave-sdk-python, I think route catalog snapshots should become a first-class test fixture. The SDK does not need to own the gateway's pricing policy. It should help applications pin the route facts that make a test result explainable later.

I checked the live pricing sources for this discussion on September 5, 2026. AIWave's public /api/pricing endpoint returned success=true, 63 route records, pricing version a42d372ccf0b5dd13ecf71203521f9d2, auto_groups=["default"], and group ratios of default=3 and vip=1. Selected AIWave route fields from that snapshot were:

Model	model_ratio	completion_ratio	cache_ratio	Enabled groups
deepseek-v4-flash	0.319	3	0.0318	default, vip, svip
deepseek-v4-pro	0.957	3	0.0333	default, vip, svip
glm-5.1	1.05	3.142857	0.32381	default, vip, svip
kimi-k3	2.25	5	0.2	svip, default, vip
qwen3-max	0.7810988945590882	4	absent	default, vip, svip

I also rechecked direct provider pages. DeepSeek's pricing page lists deepseek-v4-flash at $0.007 cache-hit input, $0.22 cache-miss input, and $0.66 output per 1M tokens off-peak, with peak rows at $0.014, $0.44, and $1.32. It lists deepseek-v4-pro at $0.022 cache-hit input, $0.66 cache-miss input, and $1.98 output off-peak, with peak rows at $0.044, $1.32, and $3.96. Z.AI lists GLM-5.3-Flash promotional rows at $0.075 input, $0.015 cached input, and $0.25 output per 1M tokens. QwenCloud's pricing guide says text generation is billed per million tokens, Batch API uses 50% of real-time token rates, and Web Search is $10 per 1K calls.

Those direct-provider rows are useful context, but they should not be mixed into an AIWave SDK test as if they were the same contract. A CI snapshot should record row owner, source URL, checked time, pricing version, effective group, requested model, resolved model, and which fields are advisory versus billable.

One possible fixture shape:

{
  "fixture": "route_catalog_snapshot_2026_09_05",
  "source_url": "https://aiwave.live/api/pricing",
  "pricing_version": "a42d372ccf0b5dd13ecf71203521f9d2",
  "effective_group": "vip",
  "required_models": ["deepseek-v4-flash", "deepseek-v4-pro", "glm-5.1"],
  "required_fields": ["model_ratio", "completion_ratio", "enable_groups"],
  "optional_fields": ["cache_ratio", "create_cache_ratio"]
}

The SDK helper should fail closed when a required model is missing, a required field disappears, the pricing version is unknown, or the effective group is not one the application reviewed. It should warn, not fail, when optional fields such as cache_ratio are absent for a route that never promised cache accounting.

In Python, the developer-facing API could stay small:

snapshot = client.aiwave.catalog.snapshot()

snapshot.assert_contract(
    pricing_version="a42d372ccf0b5dd13ecf71203521f9d2",
    effective_group="vip",
    required_models=["deepseek-v4-flash", "deepseek-v4-pro"],
)

This belongs near integration tests, rollout checks, and budget reviews. Unit tests should still mock network calls. Production code should still tolerate normal provider movement. The catalog snapshot is for the boundary between those worlds: before a route policy ships, can the team prove which catalog it accepted?

The privacy boundary is important. A catalog fixture should not contain API keys, prompts, completions, customer emails, payment identifiers, or private account data. It only needs route metadata and dated source facts. That makes it safe to attach to a release note or support investigation.

Open question: should aiwave-sdk-python expose catalog snapshots as a typed helper, or should the repo publish a reference CI example that teams copy into their own test suites?