Writing Clean Abstractions Without Hiding SDK Behavior

Every lesson so far in this unit has added a layer between application code and the OpenAI SDK: service classes, injected dependencies, typed models, decorators, custom exceptions. Each layer is valuable, but each one is also a place where an important detail of the SDK's real behavior can accidentally get hidden from the developer using the abstraction — sometimes with serious consequences. This lesson is about the tension between the two goals every abstraction has to balance: making code simpler to use, and not lying about what actually happens underneath.

What "Hiding Behavior" Means, Concretely

An abstraction hides behavior when it makes a decision on the caller's behalf that the caller cannot see, override, or even discover without reading the abstraction's source code. This is different from hiding complexity (which is the whole point of an abstraction) — it specifically means hiding something the caller needs to know to use the system correctly or safely.

Consider a summarizer service that quietly truncates long input:

class SummarizerService:
    def __init__(self, client, model: str = "gpt-5.6-terra") -> None:
        self._client = client
        self._model = model

    def summarize(self, text: str) -> str:
        if len(text) > 10_000:
            text = text[:10_000]  # silently truncated — the caller has no idea
        response = self._client.responses.create(
            model=self._model,
            input=f"Summarize:\n\n{text}",
        )
        return response.output_text

This method looks clean and simple. It is also dangerous: a caller who passes in a 50,000-character document gets a summary of only the first 10,000 characters, with no indication that 80% of the input was ignored. If this summary is used to make a decision — flagging a contract clause, extracting a compliance obligation — the missing 80% could contain exactly the detail that mattered, and nobody would know to look for it.

The Fix: Surface the Decision, Don't Hide It

A clean abstraction still simplifies the common case, but makes consequential decisions visible and, where reasonable, overridable:

class InputTooLongError(Exception):
    def __init__(self, length: int, max_length: int) -> None:
        super().__init__(
            f"Input is {length} characters, which exceeds the maximum of {max_length}."
        )
        self.length = length
        self.max_length = max_length


class SummarizerService:
    def __init__(self, client, model: str = "gpt-5.6-terra", max_input_length: int = 10_000) -> None:
        self._client = client
        self._model = model
        self._max_input_length = max_input_length

    def summarize(self, text: str) -> str:
        if len(text) > self._max_input_length:
            raise InputTooLongError(len(text), self._max_input_length)
        response = self._client.responses.create(
            model=self._model,
            input=f"Summarize:\n\n{text}",
        )
        return response.output_text

Now the limit is explicit (max_input_length, a constructor parameter with a sensible default), and exceeding it produces a clear, catchable error rather than silent data loss. The caller can decide how to handle it — split the document into chunks, ask the user to shorten it, or configure a higher limit if the use case justifies it — instead of unknowingly working with an incomplete summary.

Common Places Where SDK Behavior Gets Accidentally Hidden

Default parameter values that change model behavior. If a service class silently sets temperature=0 or a particular reasoning effort level without exposing that as a parameter, callers who need different behavior for a specific case have no way to get it short of bypassing the abstraction entirely.

Retry logic that masks persistent failures as occasional slowness. A retry decorator (Lesson 5) that retries five times with long delays makes a persistently failing dependency look like it is merely "slow" from the caller's perspective, delaying the moment a real, unrecoverable problem is noticed and investigated.

Swallowed or over-generalized exceptions. As discussed in Lesson 6, translating every SDK error into a single generic AIServiceError without preserving the distinction between "invalid request" and "temporary outage" hides information the caller may need to react correctly.

Automatic truncation, rounding, or reformatting of inputs or outputs. Any place where the abstraction "helpfully" modifies data without telling the caller creates a gap between what the caller believes happened and what actually happened.

Designing the Abstraction Boundary Deliberately

A useful discipline when designing a service class or wrapper is to ask, for every decision made inside it: would a caller be surprised, or potentially harmed, by not knowing this happened? If yes, that decision belongs in the public interface — as a parameter, a documented default, or a distinct exception — not buried in the implementation.

class SummarizerService:
    def __init__(
        self,
        client,
        model: str = "gpt-5.6-terra",
        max_input_length: int = 10_000,
        temperature: float = 0.3,
    ) -> None:
        self._client = client
        self._model = model
        self._max_input_length = max_input_length
        self._temperature = temperature

    def summarize(self, text: str) -> str:
        if len(text) > self._max_input_length:
            raise InputTooLongError(len(text), self._max_input_length)
        response = self._client.responses.create(
            model=self._model,
            input=f"Summarize:\n\n{text}",
            temperature=self._temperature,
        )
        return response.output_text

Notice that temperature — a parameter that meaningfully affects the model's output — is now a visible, documented constructor argument with a stated default, rather than an implicit choice buried inside the method body. A caller reading the class definition (or its generated documentation) can see exactly what governs the model's behavior, without needing to read the method's implementation.

Escape Hatches: Letting Advanced Callers Reach the Raw SDK

Sometimes the abstraction genuinely cannot anticipate every use case a caller might have — a rarely used SDK parameter, an experimental feature, a one-off debugging need. Rather than trying to expose every possible SDK parameter through the service class's interface (which quickly becomes as complicated as the SDK itself), a well-designed abstraction can expose the underlying client as an explicit escape hatch:

class SummarizerService:
    def __init__(self, client, model: str = "gpt-5.6-terra") -> None:
        self._client = client
        self._model = model

    @property
    def raw_client(self):
        """Direct access to the underlying OpenAI client for advanced use cases
        not covered by this service's methods."""
        return self._client

    def summarize(self, text: str) -> str:
        response = self._client.responses.create(
            model=self._model,
            input=f"Summarize:\n\n{text}",
        )
        return response.output_text

This is a deliberate, documented trade-off: the common case (summarize) stays simple, while raw_client gives an escape hatch for cases the abstraction was never designed to cover, instead of forcing every unusual need to be worked around inside the abstraction itself or forcing the caller to bypass the service entirely and reconstruct their own client.

Testing That the Boundary Stays Honest

Because InputTooLongError is a visible, explicit part of the interface, it can be tested directly, without a real client, confirming the abstraction fails loudly instead of silently truncating:

class FakeResponse:
    def __init__(self, output_text: str) -> None:
        self.output_text = output_text


class FakeResponsesAPI:
    def create(self, **kwargs):
        return FakeResponse("This should never be reached.")


class FakeClient:
    def __init__(self) -> None:
        self.responses = FakeResponsesAPI()


def test_summarize_raises_on_input_that_exceeds_the_limit() -> None:
    service = SummarizerService(client=FakeClient(), max_input_length=10)

    try:
        service.summarize("this text is definitely longer than ten characters")
        raised = False
    except InputTooLongError:
        raised = True

    assert raised
    print("PASS: oversized input raises InputTooLongError instead of being truncated")


test_summarize_raises_on_input_that_exceeds_the_limit()

When Simplification Is the Right Choice

Not every hidden detail is a problem. Hiding the exact shape of the SDK's response object (returning a plain string instead of a Response object, as in Lesson 1) is good abstraction, not harmful hiding — the caller does not need to know about output_text versus other possible response fields to get a summary; that detail carries no risk of surprising or harming them if it changes. The distinction is not "does this abstraction hide something" (all abstractions do, by definition) but "does this abstraction hide something the caller needs to know to use the system safely and correctly."

Common Mistakes

Treating "simple to call" as the only design goal. An abstraction that always looks clean from the outside, no matter what, tends to achieve that by quietly absorbing edge cases the caller actually needed visibility into.

Hardcoding values that materially affect output quality or cost. A hidden max_tokens limit or a hidden model substitution (silently falling back to a cheaper model under some condition) can have consequences the caller has no way to detect from the code they wrote.

No escape hatch at all. An abstraction with zero way to reach the underlying SDK forces callers with unusual, legitimate needs to work around the abstraction in fragile ways, or to duplicate its logic elsewhere.

Best Practices

Make every default that affects model behavior an explicit, documented constructor parameter, not a value hardcoded inside a method body.

Raise clear, specific exceptions instead of silently working around invalid or oversized input. A caller who receives InputTooLongError can make an informed decision; a caller whose input was silently truncated cannot.

Provide a documented escape hatch to the underlying client for legitimate cases the abstraction was not designed to handle, rather than trying to expose every SDK parameter through the wrapper's own interface.

When reviewing a service class, ask "what would surprise someone reading only this class's public interface?" Anything that would surprise them is a candidate for becoming an explicit parameter, a raised exception, or documented behavior.