Dependency Injection for AI Clients

Every unit in this course has tested application logic using fake, injected clients rather than real API calls — a FakeClient with a .responses.create() method that returns a canned object, checked with assert and print("PASS: ..."). That pattern was introduced quietly, as a testing convenience. This lesson generalizes it into a first-class architectural principle for a whole application: dependency injection (DI).

What Dependency Injection Is

Dependency injection means a piece of code receives the objects it depends on from the outside, rather than creating them itself. For an OpenAI-backed application, the "dependency" is almost always the SDK client (or a service class wrapping it, as in Lesson 1).

Without DI:

from openai import OpenAI


class Summarizer:
    def __init__(self) -> None:
        self._client = OpenAI()  # created internally — hard-coded dependency

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

With DI:

from openai import OpenAI


class Summarizer:
    def __init__(self, client: OpenAI) -> None:
        self._client = client  # received from outside — injected dependency

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

The difference looks small — one line moves from inside the class to its constructor signature — but it changes who controls the dependency. In the first version, Summarizer can never be tested, configured, or reused without a real OpenAI() client and, by extension, a real API key and network access. In the second version, anything that satisfies the shape .responses.create(...) -> object with .output_text can be passed in: a real client, a fake client, a client pointed at a different base URL, or a client with custom retry settings.

Why Dependency Injection Matters for AI Clients

AI clients are a particularly important place to apply DI because they are:

• Expensive and slow to call for real. A test suite that hits the live API on every run is slow, costs money, and produces different results every time depending on model behavior.
• A source of nondeterminism. Model outputs are not guaranteed to be identical between calls, which makes assertions on exact output unreliable if you're calling the real API.
• A single point of configuration. API keys, base URLs, timeouts, and retry policy are typically set once and should not be duplicated across every class that happens to need a client.

DI solves all three: tests inject a fake client with fixed, deterministic output; the API key and connection settings live in exactly one place (wherever the real client is constructed); and any class that needs a client just declares that need in its constructor, without knowing where the client comes from.

Constructor Injection

The style used above — passing the dependency as a constructor argument — is called constructor injection, and it is the default choice for most Python applications:

class TicketRouter:
    def __init__(self, classifier: "TicketClassifierService") -> None:
        self._classifier = classifier

    def route(self, ticket_text: str) -> str:
        category = self._classifier.classify_ticket(ticket_text)
        queues = {
            "billing": "billing-queue",
            "technical": "tech-queue",
            "account": "account-queue",
        }
        return queues.get(category, "general-queue")

TicketRouter does not create a TicketClassifierService itself, and it does not know whether that service is backed by a real or fake client. It only knows the service's public interface (classify_ticket). This is the essence of DI: dependencies are declared as parameters, and something else — application startup code, or a test — decides what to supply.

Composition at the Application's Entry Point

If every class receives its dependencies from outside, something still has to construct the real objects somewhere. That "somewhere" should be as close to the application's entry point as possible — a main() function, a web framework's startup hook, or a small bootstrap.py module — never scattered throughout business logic.

from openai import OpenAI


def build_ticket_router() -> TicketRouter:
    client = OpenAI()  # reads OPENAI_API_KEY from the environment
    classifier = TicketClassifierService(client=client, model="gpt-5.6-terra")
    return TicketRouter(classifier=classifier)


def main() -> None:
    router = build_ticket_router()
    queue = router.route("I was charged twice this month.")
    print(f"Routed to: {queue}")


if __name__ == "__main__":
    main()

This is sometimes called the composition root — the one place in the application where concrete objects are wired together. Everywhere else in the codebase, code depends only on abstractions (a client-shaped object, a service class's public methods), never on concrete construction details like OpenAI() or environment variables.

Testing With Injected Fakes

Because TicketRouter and TicketClassifierService both take their dependencies as constructor arguments, a test can assemble the whole chain using fakes, with no real client anywhere:

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


class FakeResponsesAPI:
    def __init__(self, canned_text: str) -> None:
        self._canned_text = canned_text

    def create(self, **kwargs):
        return FakeResponse(self._canned_text)


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


def test_router_sends_billing_tickets_to_billing_queue() -> None:
    fake_client = FakeClient(canned_text="billing")
    classifier = TicketClassifierService(client=fake_client)
    router = TicketRouter(classifier=classifier)

    queue = router.route("Why was I charged twice?")

    assert queue == "billing-queue"
    print("PASS: billing category routes to billing-queue")


test_router_sends_billing_tickets_to_billing_queue()

Notice that this test exercises two real, unmodified classes (TicketClassifierService and TicketRouter) end to end — only the bottom-most dependency, the client, is faked. This is the general shape of DI-based testing: fake the boundary that talks to the outside world (the network), and let all of your own logic run for real.

Injection via Function Parameters

Not every dependency needs a class. A plain function can also receive its dependency as a parameter instead of importing a global client:

def summarize_with(client, text: str, model: str = "gpt-5.6-terra") -> str:
    response = client.responses.create(
        model=model,
        input=f"Summarize:\n\n{text}",
    )
    return response.output_text

This works well for small utility functions used in scripts or notebooks. As soon as a function starts accumulating multiple dependencies or gets called from many places with the same dependency, wrapping it in a class (Lesson 1) usually keeps the calling code cleaner, since a class's constructor stores the dependency once instead of every call site re-passing it.

Framework-Provided Dependency Injection

Web frameworks such as FastAPI provide a formal DI mechanism where a function declares its dependencies as parameters with default values, and the framework resolves and injects them automatically per request:

from fastapi import Depends, FastAPI

app = FastAPI()


def get_summarizer() -> Summarizer:
    return Summarizer(client=OpenAI())


@app.post("/summarize")
def summarize_endpoint(text: str, summarizer: Summarizer = Depends(get_summarizer)) -> dict:
    return {"summary": summarizer.summarize(text)}

Note: FastAPI's Depends mechanism is specific to that framework; the underlying principle — pass dependencies in rather than construct them inside the function — is the same manual pattern shown throughout this lesson, just automated by the framework.

This does not replace manual constructor injection; it automates the same idea at the web-framework layer, while the Summarizer class itself still uses plain constructor injection underneath, which is exactly why it remains just as testable in isolation.

Common Mistakes

Constructing the client deep inside business logic. If TicketClassifierService.classify_ticket() created its own OpenAI() client the first time it was called, no test could ever substitute a fake — the dependency would be invisible from the outside.

Passing configuration values instead of the dependency itself. Injecting an API key string and having each class build its own client from it re-introduces duplication and makes tests still need real credentials. Inject the constructed client (or service), not the raw configuration used to build it.

Over-injecting. Not everything needs to be injected — a pure function with no I/O (like a text-cleaning helper) gains nothing from DI and only adds noise. Reserve DI for dependencies that are expensive, external, or need to vary between production and tests.

Best Practices

Depend on the narrowest interface you need. If a class only ever calls client.responses.create(...), it does not need the full OpenAI type hint — accepting any object with that shape (see Lesson 3 on structural typing with Protocol) keeps fakes simple and decouples code from the SDK's concrete class.

Keep one composition root. Construct real clients and wire dependencies together in exactly one place per application (or one per entry point, if there are several) so it is always clear where production wiring happens.

Make fakes as small as possible. A fake client should implement only the methods your code actually calls — resist the temptation to build a full mock of the SDK when three lines of a hand-written fake class do the job clearly and legibly.

Write the test before or alongside the class. Since DI is what makes a class testable in the first place, treating "can I test this without a real API call?" as a design check while writing a class catches accidental hidden dependencies early.