A client you can still use when you configured it wrong

Every time you wire a chat client together, a question arises: you set a temperature, but the chosen model doesn't support it. Go has a clear stance on this matter, favoring a yes or no response. The constructor convention is widely accepted, following a return (T, error) pattern. When an error occurs, the T is no longer usable.

This approach assumes construction either succeeded or failed entirely, such as opening a file, dialing a socket, or parsing a document. A chat client, however, is made up of various components like providers, models, credentials, timeouts, endpoints, sampling controls, streaming, tool support, fallback chains, and numerous customizable options.

Constructing such a client involves making multiple small decisions, and when one fails, the impact is often partial. Most of these components work fine, but the one that doesn't, usually the least important one, remains unchanged. The binary outcome doesn't offer a clear indication of what went wrong, so the library resorts to two undesirable outcomes: either accepting a malfunctioning client or concealing the issue, leading users to believe it applies universally.

To address this, a new approach is proposed. If you build a client with an invalid combination, instead of discarding the entire client, you receive a working version with the functional parts intact, accompanied by a detailed list of what couldn't be applied. This error message not only identifies the dropped setting but also explains why it happened.

The structure includes the name of the dropped setting, the required capability, and a concise explanation of the reason behind the failure. This detailed error message empowers developers to rectify the issue effectively. By providing a comprehensive receipt, the design ensures that developers have all the necessary information to troubleshoot and resolve the problem.

While some argue against this approach, claiming that it might confuse callers who ignore the error details, the strict contract ultimately protects users from encountering a completely broken client. The focus is on delivering a complete, specific, and actionable error message, empowering developers to take appropriate actions rather than silently swallowing errors.

Although this design shifts the decision-making responsibility from the library to the caller, it still safeguards against the worst-case scenario of a completely malfunctioning client.