Packaging Reusable OpenAI SDK Utilities

Everything built in this unit so far — service classes, dependency injection, typed models, decorators, custom exceptions, careful abstraction design — has lived inside a single application's codebase. Once a team builds several AI-powered features across multiple projects, the same service classes, retry decorators, and exception hierarchies tend to get copy-pasted from one repository into the next. Packaging turns that shared code into an installable Python package — a proper internal library — so it is written once, versioned, and installed as a dependency everywhere it is needed, instead of copied and drifting out of sync.

Why Copy-Pasting Shared Code Fails Over Time

Imagine a retry decorator (Lesson 5) and an AIServiceError hierarchy (Lesson 6) copy-pasted into three different projects at a company. Six months later, someone fixes a bug in the retry decorator's delay logic in Project A. Unless someone remembers to manually copy that fix into Projects B and C, those two projects keep running the buggy version indefinitely — there is no mechanism connecting the three copies, and no way to know from Project B's code alone that a fix exists elsewhere. This is the core problem packaging solves: one canonical version of shared code, installed (and upgraded) as a versioned dependency, instead of N independent copies that silently diverge.

The Minimal Anatomy of an Installable Python Package

A modern Python package needs, at minimum: a directory containing your source code, an __init__.py (or, for namespace packages, none — but an explicit __init__.py is the simpler default), and a pyproject.toml file describing the package's metadata and dependencies.

ai-toolkit/
├── pyproject.toml
├── README.md
└── src/
    └── ai_toolkit/
        ├── __init__.py
        ├── service.py
        ├── decorators.py
        ├── exceptions.py
        └── settings.py

This is the src layout — source code lives under src/<package_name>/ rather than directly at the project root. It is the currently recommended layout because it prevents a common class of bug where tests accidentally import the local, uninstalled source directory instead of the actually-installed package, which can mask packaging mistakes that would otherwise only surface after publishing.

A minimal pyproject.toml for this package:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "ai-toolkit"
version = "0.1.0"
description = "Shared OpenAI SDK service classes, decorators, and exceptions for internal AI features."
requires-python = ">=3.10"
dependencies = [
    "openai>=1.0,<2.0",
    "pydantic>=2.0,<3.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "mypy>=1.0",
]

Note: pyproject.toml's structure is defined by Python packaging standards (PEP 621 and related), but the specific build backend (hatchling here; setuptools and poetry-core are common alternatives) and its exact configuration options can vary and evolve. Confirm current conventions against the Python Packaging User Guide before setting up a real package.

Each field here does real work. [build-system] tells any tool that installs this package (like pip) which backend actually builds the distributable artifact. [project] holds metadata: the package's importable name, its version (used for dependency resolution — see below), and its own dependencies, each pinned to a version range rather than left unconstrained.

Why Version Pinning in Dependencies Matters

Notice "openai>=1.0,<2.0" rather than a bare "openai". An unconstrained dependency lets any future version of the OpenAI SDK — including one with breaking changes — be installed silently the next time someone runs pip install. Pinning a range communicates: "this package was built and tested against the 1.x line of the SDK, and has not been verified against 2.x." When the SDK does release a 2.0, upgrading the internal library's own dependency range becomes a deliberate, tested decision (see Lesson 10) rather than something that happens by accident to whoever installs the package next.

What Goes Inside the Package

The package's own source mirrors the patterns from earlier lessons, but written once and exported cleanly:

# src/ai_toolkit/exceptions.py

class AIServiceError(Exception):
    """Base class for all errors raised by ai_toolkit integrations."""


class AIRateLimitedError(AIServiceError):
    """Raised when the AI provider is rate-limiting requests."""


class AITransientError(AIServiceError):
    """Raised for errors that are likely temporary and might succeed on retry."""

# src/ai_toolkit/service.py

from openai import APIError, APITimeoutError, RateLimitError

from ai_toolkit.exceptions import AIRateLimitedError, AIServiceError, AITransientError


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:
        try:
            response = self._client.responses.create(
                model=self._model,
                input=f"Summarize:\n\n{text}",
            )
            return response.output_text
        except RateLimitError as error:
            raise AIRateLimitedError("Rate limited by the AI provider.") from error
        except APITimeoutError as error:
            raise AITransientError("Request to the AI provider timed out.") from error
        except APIError as error:
            raise AIServiceError(f"AI provider error: {error}") from error

# src/ai_toolkit/__init__.py

from ai_toolkit.exceptions import AIRateLimitedError, AIServiceError, AITransientError
from ai_toolkit.service import SummarizerService

__all__ = [
    "AIRateLimitedError",
    "AIServiceError",
    "AITransientError",
    "SummarizerService",
]

The __init__.py re-exports the package's public names so that consumers can write from ai_toolkit import SummarizerService, AIServiceError instead of needing to know the internal module layout (ai_toolkit.service, ai_toolkit.exceptions). The __all__ list is a further, explicit statement of what is public API and what is internal implementation detail — a name left out of __all__ (even if technically importable) signals to consumers that it is not meant to be relied upon and might change without notice.

Installing the Package Locally During Development

While developing both the library and an application that uses it side by side, an editable install lets changes to the library's source be picked up immediately, without reinstalling after every edit:

pip install -e /path/to/ai-toolkit

Once published (to a private package index, or referenced directly via a git URL), consuming applications declare it as an ordinary dependency in their own pyproject.toml:

[project]
dependencies = [
    "ai-toolkit>=0.1.0,<0.2.0",
]

Testing a Package in Isolation

A packaged library should ship its own test suite, using exactly the dependency-injection pattern from Lesson 2 — testing the library's own classes against fake clients, with no dependency on any consuming application:

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_summarizer_service_returns_model_output() -> None:
    from ai_toolkit import SummarizerService

    service = SummarizerService(client=FakeClient(canned_text="A concise summary."))

    result = service.summarize("Some long input text.")

    assert result == "A concise summary."
    print("PASS: SummarizerService returns the fake client's canned output")


test_summarizer_service_returns_model_output()

This test lives inside the library's own test suite (conventionally under tests/ at the project root) and is run whenever the library itself changes — independent of any application that eventually installs it.

Semantic Versioning

The version = "0.1.0" field follows semantic versioning (MAJOR.MINOR.PATCH): increment PATCH for backward-compatible bug fixes, MINOR for backward-compatible new functionality, and MAJOR for breaking changes to the public API. This convention lets consuming applications express exactly how much change they are willing to accept automatically (ai-toolkit>=0.1.0,<0.2.0 accepts patch and minor updates within 0.1.x, but never a breaking 0.2.0 change) — which is precisely what makes safe automatic upgrades possible at all.

Common Mistakes

Publishing a package with no version constraints on its own dependencies. This allows a future, possibly incompatible release of the OpenAI SDK (or Pydantic, or any other dependency) to be silently installed alongside the library, breaking consumers without warning.

Exposing internal implementation modules as if they were public API. If consumers start importing ai_toolkit.service.SummarizerService directly instead of ai_toolkit.SummarizerService, refactoring the internal module layout later becomes a breaking change even though the intended public API never changed.

Skipping the package's own test suite because "it's just internal code." Internal libraries used by multiple teams cause more widespread damage when broken than a single application's own bug, precisely because many things depend on them at once.

Best Practices

Use the src layout and export a clean public API through __init__.py and __all__. This creates a clear boundary between what consumers are meant to depend on and what remains free to change.

Pin dependency version ranges deliberately, and update them as a conscious decision, not by accident. This directly sets up the version-evolution practices covered in Lesson 10.

Follow semantic versioning strictly, especially for breaking changes. Consumers rely on the version number alone to decide whether an upgrade is safe to take automatically.

Give the package its own independent test suite, using fakes and dependency injection exactly as application code does. A library that cannot be tested without a real API key is a library nobody will want to depend on.