Why One Configuration Is Never Enough

A development environment and a production environment have different needs even when they run the exact same code. In development, you want verbose logging, a cheap or fast model for quick iteration, and tolerance for occasional failures. In production, you want conservative logging (no sensitive data), the model your product actually depends on, strict timeouts, and alerting on any failure. Using identical configuration for both is not just wasteful — it is risky: a developer testing locally with the production API key can burn through production rate limits or accidentally cause production-billed usage from a laptop.

Environment-specific configuration means the same codebase behaves differently depending on which environment it is told it is running in, without any code branching on "if I'm in prod, do X." The branching happens once, in configuration, and the rest of the application just reads values.

The APP_ENV Switch

The standard mechanism is a single environment variable — commonly named APP_ENV or ENVIRONMENT — that names the current environment ("development", "staging", "production"), plus a small amount of code that loads the right values based on it.

import os
from dataclasses import dataclass
from enum import Enum


class Environment(str, Enum):
    DEVELOPMENT = "development"
    STAGING = "staging"
    PRODUCTION = "production"


@dataclass(frozen=True)
class AppConfig:
    environment: Environment
    openai_api_key: str
    model: str
    log_level: str
    request_timeout: float


_DEFAULTS = {
    Environment.DEVELOPMENT: {
        "model": "gpt-5.6-terra-mini",
        "log_level": "DEBUG",
        "request_timeout": 60.0,
    },
    Environment.STAGING: {
        "model": "gpt-5.6-terra",
        "log_level": "INFO",
        "request_timeout": 30.0,
    },
    Environment.PRODUCTION: {
        "model": "gpt-5.6-terra",
        "log_level": "WARNING",
        "request_timeout": 15.0,
    },
}


def load_config() -> AppConfig:
    env_name = os.environ.get("APP_ENV", "development")
    try:
        environment = Environment(env_name)
    except ValueError as exc:
        valid = ", ".join(e.value for e in Environment)
        raise RuntimeError(f"APP_ENV must be one of: {valid}") from exc

    defaults = _DEFAULTS[environment]
    api_key = os.environ.get("OPENAI_API_KEY")
    if not api_key:
        raise RuntimeError("OPENAI_API_KEY is not set")

    return AppConfig(
        environment=environment,
        openai_api_key=api_key,
        model=os.environ.get("OPENAI_MODEL", defaults["model"]),
        log_level=os.environ.get("LOG_LEVEL", defaults["log_level"]),
        request_timeout=float(
            os.environ.get("OPENAI_TIMEOUT_SECONDS", defaults["request_timeout"])
        ),
    )

Two design choices here matter. First, Environment is an Enum, not a plain string. This means a typo like APP_ENV=produciton fails immediately with a clear error listing the valid values, instead of silently falling through to development-style defaults in what is actually a production deployment — a mistake that is dangerous precisely because nothing about it looks wrong until you look closely. Second, every default can still be overridden by an explicit environment variable (os.environ.get("OPENAI_MODEL", defaults["model"])). The per-environment table supplies sensible defaults, but an operator can always override a specific value without touching code — useful when, for example, you want to test a new model in production for a single deployment without changing the default for everyone.

Per-Environment .env Files

During local development, typing environment variables into your shell every time is tedious, and you cannot reasonably export OPENAI_API_KEY=... for every teammate. The common convention is a .env file — a plain text file of KEY=value lines — loaded by a library such as python-dotenv, with a separate file per environment: .env.development, .env.staging, and (rarely, and carefully) .env.production.

# .env.development
APP_ENV=development
OPENAI_API_KEY=sk-dev-xxxxxxxxxxxxxxxx
OPENAI_MODEL=gpt-5.6-terra-mini
LOG_LEVEL=DEBUG

from dotenv import load_dotenv
import os

env_name = os.environ.get("APP_ENV", "development")
load_dotenv(f".env.{env_name}", override=False)

config = load_config()

load_dotenv reads the file named .env.{env_name} and sets each key as an environment variable if it is not already set — override=False is deliberate: real environment variables set by the deployment platform (a container orchestrator, a CI system) should always win over anything in a local .env file. This ordering matters because it means the exact same code path works both for a developer running locally with a .env.development file and for a production container that has no .env file at all and relies entirely on variables injected by the platform.

.env files should never be committed to version control — each one typically holds either a real secret (development API keys still cost money and can be misused) or, in the case of a hypothetical .env.production, the actual production secret. A .gitignore entry for .env* (with a tracked .env.example containing placeholder values and no real secrets) is the standard pattern. Lesson 5 in this unit goes further into how production secrets are actually delivered to a deployed service — in most cloud deployments, it is not a .env file at all, but a secret store the platform injects at runtime.

Feature Flags

A feature flag is a configuration value that turns a piece of functionality on or off without a code deployment. In an OpenAI SDK application, a common use is gating a new prompt design, a new model, or an expensive feature (like automatically running a second verification call) behind a flag that can differ between environments — or even be enabled for a percentage of production traffic — without redeploying code.

from dataclasses import dataclass


@dataclass(frozen=True)
class FeatureFlags:
    use_verification_pass: bool
    enable_streaming: bool


def load_feature_flags() -> FeatureFlags:
    return FeatureFlags(
        use_verification_pass=os.environ.get("FF_VERIFICATION_PASS", "false") == "true",
        enable_streaming=os.environ.get("FF_STREAMING", "true") == "true",
    )


def answer_question(client, question: str, flags: FeatureFlags, model: str) -> str:
    response = client.responses.create(model=model, input=question)
    answer = response.output_text

    if flags.use_verification_pass:
        check = client.responses.create(
            model=model,
            input=f"Verify this answer is factually consistent: {answer}",
        )
        answer = f"{answer}\n\n[Verified: {check.output_text}]"

    return answer

use_verification_pass is a good example of what feature flags are for in an AI application specifically: the verification pass roughly doubles the API cost and latency of every request, so you might enable it in staging to validate the approach, keep it off in production until you are confident in it, and then flip it on for production once validated — all without touching answer_question itself. The function reads the flag value it was given; it does not know or care where that value came from, which is what keeps it testable with a fake FeatureFlags instance in unit tests.

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


class FakeClient:
    def __init__(self, replies: list[str]) -> None:
        self._replies = list(replies)
        self.calls = 0

    class _Responses:
        def __init__(self, outer: "FakeClient") -> None:
            self._outer = outer

        def create(self, model: str, input: str) -> FakeResponse:
            self._outer.calls += 1
            return FakeResponse(self._outer._replies[self._outer.calls - 1])

    @property
    def responses(self) -> "FakeClient._Responses":
        return FakeClient._Responses(self)


def test_verification_pass_adds_a_second_call() -> None:
    client = FakeClient(["The sky is blue.", "Consistent."])
    flags = FeatureFlags(use_verification_pass=True, enable_streaming=False)

    result = answer_question(client, "What color is the sky?", flags, "gpt-5.6-terra")

    assert client.calls == 2
    assert "Verified: Consistent." in result
    print("PASS: verification pass triggers a second call and appends its result")


test_verification_pass_adds_a_second_call()

This test never touches the network — FakeClient returns pre-set replies and counts how many times it was called — but it verifies real behavior: that turning the flag on results in exactly two calls instead of one, and that the verification text is appended to the output. This is the value of designing answer_question to receive flags as a parameter rather than reading a global: the feature-flag logic is exercised by a fast, deterministic test with no API key and no cost.

Comparison: .env Files vs. Platform-Injected Environment Variables

The important takeaway from this table is not that one mechanism is universally better, but that your application code should not need to know which one supplied a given value — it should just read os.environ. That indifference is exactly what load_config() earlier in this lesson achieves.

Common Mistakes

Reusing the same API key across development and production. A bug in a local script, or an accidental infinite loop while testing, then consumes production quota and shows up on the production bill. Provision separate keys per environment, even if they belong to the same OpenAI organization.

Committing a .env file to version control. Even a .env.development file often contains a real, working API key. Once committed, it exists in git history permanently, even if the file is later deleted or gitignored — the key must be revoked and rotated, not just removed.

Letting feature flags accumulate indefinitely. A flag added to test a change and never removed becomes a second, undocumented configuration surface that future developers have to reason about. Once a flagged feature is fully rolled out and stable, remove the flag and the old code path.

Best Practices

Make the environment name itself a validated value, using an Enum or an explicit allow-list, so a typo in APP_ENV fails loudly rather than silently defaulting to the wrong environment's behavior.

Keep per-environment defaults in code, but allow every value to be overridden by an explicit environment variable. This gives you sensible out-of-the-box behavior per environment while still allowing operational overrides without a code change.

Design flag-gated functions to receive the flag values as parameters, not to read global state, so the branching logic can be exercised in fast, dependency-injected tests exactly like any other configuration-dependent code path in this course.