Building Internal Python Libraries for AI Teams

Lesson 8 covered the mechanics of turning shared code into an installable package. This lesson is about the harder, less mechanical problem: what actually belongs in a shared internal library for a team building multiple AI-powered features, how to design that library so several teams can depend on it without stepping on each other, and how to keep it useful as the number of consumers and use cases grows.

What Belongs in a Shared Library, and What Doesn't

Not everything that appears in more than one project belongs in a shared library. The right test is stability and generality: does this code express a concern that is the same across every reasonable use case, or does it express a business decision specific to one feature?

A retry decorator (Lesson 5), a base exception hierarchy (Lesson 6), a Settings base class (Lesson 4), and a typed wrapper around common SDK call patterns (Lesson 1) are strong candidates — they are infrastructure concerns that do not change based on what a specific feature does with the model. A prompt template for classifying support tickets into "billing/technical/account" categories is not — that is business logic specific to one feature, and putting it in a shared library couples unrelated teams to each other's product decisions.

# Belongs in the shared library — infrastructure, not business logic
class AIServiceError(Exception):
    """Base class for all AI integration errors across the organization."""


def retry(max_attempts: int = 3, delay_seconds: float = 1.0):
    ...  # generic retry logic, as in Lesson 5


# Does NOT belong in the shared library — specific to one product feature
def classify_support_ticket(client, ticket_text: str) -> str:
    ...  # this team's specific prompt and category list

A useful rule: if changing this code would require asking "does this break someone else's specific feature," it is infrastructure and belongs in the shared library. If changing it would require asking "does this match what our product does," it is business logic and belongs in that team's own codebase.

Designing for Multiple, Independent Consumers

A library used by one team can get away with breaking changes communicated informally ("hey, I changed this, update your code"). A library used by five teams across an organization cannot — informal communication does not scale, and different teams upgrade on different schedules. This changes several design decisions:

Every public class needs a stable constructor signature. Adding a new required parameter to SummarizerService.__init__ breaks every consumer simultaneously. Adding an optional parameter with a sensible default does not.

# Breaking change — every existing caller must be updated immediately
def __init__(self, client, model: str, max_input_length: int) -> None:
    ...

# Backward-compatible change — existing callers are unaffected
def __init__(self, client, model: str = "gpt-5.6-terra", max_input_length: int = 10_000) -> None:
    ...

Deprecation, not deletion, is the default way to remove something. Rather than deleting an old method outright, mark it deprecated, keep it functional, and give consumers a migration window:

import warnings


class SummarizerService:
    def summarize_text(self, text: str) -> str:
        """Deprecated: use summarize() instead. Will be removed in version 2.0."""
        warnings.warn(
            "summarize_text() is deprecated and will be removed in 2.0; use summarize() instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        return self.summarize(text)

    def summarize(self, text: str) -> str:
        ...

warnings.warn with DeprecationWarning is the standard Python mechanism for this: it does not break anything immediately, but it surfaces a visible warning (which most test runners and linters can be configured to treat as an error) that tells consuming teams exactly what to change and by when.

Organizing the Library Around Capabilities, Not Layers

A common design mistake in shared libraries is organizing modules by technical layer (models.py, services.py, utils.py) rather than by capability. This tends to produce a utils.py that grows without bound, holding unrelated helper functions that share no real relationship beyond "didn't fit elsewhere."

# Organized by technical layer — tends to become a dumping ground
ai_toolkit/
├── models.py       # every typed model, for every feature
├── services.py      # every service class, for every feature
└── utils.py         # everything that didn't fit above

# Organized by capability — each module has one clear reason to change
ai_toolkit/
├── summarization/
│   ├── models.py
│   └── service.py
├── classification/
│   ├── models.py
│   └── service.py
├── retry.py
├── exceptions.py
└── settings.py

The capability-organized layout groups a feature's model and service together (so summarization/ can be understood, tested, and versioned somewhat independently), while genuinely cross-cutting concerns (retry.py, exceptions.py, settings.py) stay at the top level, since they apply to every capability rather than belonging to any one of them.

Documentation as Part of the Library, Not an Afterthought

For an internal library used by teams other than its author, the README (or equivalent documentation) is not optional polish — it is the primary interface most consumers will actually read before writing code against the library:

## Quick Start

```python
from openai import OpenAI
from ai_toolkit import SummarizerService

client = OpenAI()
service = SummarizerService(client=client)

summary = service.summarize("Long document text here...")
```

## Testing Your Code Against ai_toolkit

Use `ai_toolkit.testing.FakeClient` to test code that depends on this library
without making real API calls:

```python
from ai_toolkit.testing import FakeClient

def test_my_feature():
    fake_client = FakeClient(canned_text="expected output")
    ...
```

That last section matters specifically for a shared library: if every consuming team has to re-invent their own fake client and fake response classes (as shown repeatedly throughout this unit), that is duplicated effort the library itself can eliminate by shipping a small testing module with ready-made fakes.

Shipping Test Doubles as Part of the Library

Extending this idea, a mature internal library often ships a testing submodule containing the exact fake classes needed to test code that depends on it — turning a pattern every team would otherwise reimplement into a shared, tested utility:

# src/ai_toolkit/testing.py

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:
    """A minimal fake OpenAI client for testing code built on ai_toolkit,
    without making real API calls."""

    def __init__(self, canned_text: str = "fake output") -> None:
        self.responses = FakeResponsesAPI(canned_text)

Consuming teams then write their own tests using this shared fake, rather than each hand-rolling an equivalent class:

def test_consumer_code_handles_summarizer_output() -> None:
    from ai_toolkit import SummarizerService
    from ai_toolkit.testing import FakeClient

    service = SummarizerService(client=FakeClient(canned_text="Executive summary."))

    result = service.summarize("A very long report.")

    assert result == "Executive summary."
    print("PASS: consumer test using ai_toolkit's shared FakeClient succeeds")


test_consumer_code_handles_summarizer_output()

This directly extends the dependency-injection testing pattern used throughout this course: because every consumer already tests against fake, injected clients rather than real ones, the library can provide the one correct fake implementation centrally, instead of every team writing a slightly different (and possibly subtly wrong) version of the same thing.

Governance: Who Can Change the Shared Library

As more teams depend on a library, uncoordinated changes become a real risk — one team's convenient tweak can silently break another team's production feature. Establishing a lightweight review process (a required code review from the library's maintainers, a changelog entry for every release, a deprecation policy like the one shown above) becomes necessary exactly at the point where the library has multiple independent consumers, even though it would be unnecessary overhead for a single-team project.

Common Mistakes

Adding feature-specific business logic to the shared library "just this once." This is how shared libraries accumulate unrelated, tightly coupled code that makes every future change riskier for every consumer, not just the one that needed the feature.

Making breaking changes without a deprecation path. Removing or changing a method's signature with no warning period forces every consuming team to fix their code on the library maintainer's schedule, not their own.

Treating documentation as optional because "the code is self-explanatory." For a library with consumers outside the author's own team, undocumented behavior is effectively unusable behavior — nobody will read the source code first.

Best Practices

Apply a stability test before adding anything to the shared library: infrastructure, or business logic? Only genuinely cross-cutting, stable concerns belong in shared code.

Prefer additive, backward-compatible changes; deprecate before removing. DeprecationWarning plus a stated removal version gives every consuming team a predictable upgrade path.

Ship a testing submodule with ready-made fakes for the library's own classes. This extends the course-wide dependency-injection testing pattern to every team that depends on the library, instead of each team reimplementing it independently.

Organize modules by capability, and keep genuinely cross-cutting code (retry logic, exceptions, settings) separate and clearly labeled as shared infrastructure.