The Provider Adapter Was the Weird Part

I thought “OpenAI-compatible” meant I could trust the same stream everywhere. Then one provider sent a chunk my parser did not expect, and I remembered that compatibility is a promise you still have to test.

The request looked familiar: messages in, streamed tokens out. The difference showed up in the details — an empty delta, a different finish event, tool-call fragments arriving in another shape, or a response that ended without the marker my parser was waiting for.

None of those behaviours felt unreasonable from the provider's point of view. They were unreasonable for my adapter because I had quietly treated one implementation's behaviour as the contract.

I am tightening the boundary now. The provider-specific code deals with the weirdness, while the rest of the application gets one small event model for text, tool calls, usage, errors, and completion.

The important tests are not just “does a normal request work?” I want streams with empty chunks, delayed chunks, malformed data, tool calls, provider errors, and a clean shutdown when the connection ends early.

I still like the idea of an OpenAI-compatible API. I just think of the word compatible as an invitation to write contract tests, not as a reason to skip them.