Abstraction Layer

An abstraction layer is a piece of code you own that sits between your application and an external dependency, exposing an interface defined in your own terms. The application calls your interface; the layer translates that into whatever the current provider expects. Nothing about the outside world is hidden by magic — the layer simply concentrates knowledge of the provider in one place instead of spreading it through the codebase. The benefit that gets cited most is portability, and it is real but often overstated. A layer makes swapping a provider a bounded project rather than an open-ended one, because the code that knows about the vendor is enumerable. It does not make the swap free: differences in behaviour, quality and error semantics still have to be handled, and those are not things an interface can absorb. The benefits that get cited least are usually the ones that pay for the layer in the first month. A single place to add retries, timeouts, rate-limit handling and circuit breaking. A single place to log requests and costs consistently. A single place to inject a test double, which is the difference between a fast test suite and one that calls a paid API. And a single vocabulary in your domain rather than the vendor's, so that the rest of the code reads as your product rather than as somebody's SDK. The design failure to avoid is abstracting at the wrong level. A layer that mirrors the provider's API one-to-one buys nothing, because your interface changes whenever theirs does. A layer that models your use case — summarise this document, classify this ticket, answer this question with these sources — leaves you free to change how it is fulfilled. The right seam is a capability of your product, not a shape of somebody else's endpoint. For AI dependencies the layer should own the whole configuration, not just the call. The prompt, the model version, the sampling parameters, the tool definitions, the retrieval settings and the output schema belong together, because behaviour is a product of all of them. That grouping is what lets you version behaviour as one artefact, run an evaluation against it, and roll it back without a code change. The cost is worth naming honestly. Every abstraction is code to maintain, a place where features get delayed because the interface has to grow first, and a temptation to build a framework nobody asked for. The proportionate version is thin, written for the two or three operations you actually perform, and extended only when a second real use appears — not designed up front for every capability a provider might one day offer.