Base Image Planning Tool

Build a helper that turns a LangGraph configuration into a concrete Docker base image and tag plan while surfacing any distro-related cautions. Load and validate the config from the provided path, prefer the hardened wolfi distro by default, and emit warnings whenever the chosen base image or distro is not wolfi. Tags should surface the runtime version, distro choice, and any pinned API version.

Capabilities

Base image selection

• Loading a config with python_version set to 3.12 and image_distro set to "wolfi" produces a base_image string that includes both values, returns distro as "wolfi", and emits a tag for image_name="acme/runtime" that preserves the Python version and distro. @test

Override handling and warnings

• When the config specifies base_image as "python:3.11-slim" and image_name="acme/override", the result uses that exact base image, keeps the Python version visible in the tag, and adds a warning that the chosen base is not the preferred distro. @test
• With image_distro set to "debian" for python_version 3.13 and image_name="acme/debian", the plan marks the distro as debian, the tag reflects that distro choice, and the warnings include guidance to prefer the hardened default. @test

API version pinning

• Providing api_version "1.2.3" and image_name="acme/pinned" while keeping image_distro as "wolfi" yields a tag that encodes the API version alongside the runtime version, with no warnings when the distro is already the preferred one. @test

Implementation

@generates

API

from typing import Optional

def plan_image(config_path: str, *, image_name: str, platform: Optional[str] = None) -> dict[str, object]:
    """
    Build an image plan from the given config file.
    Returns a dict with keys:
    - base_image: str
    - tag: str
    - distro: str
    - warnings: list[str]
    """

Dependencies { .dependencies }

langgraph-cli { .dependency }

Provides configuration parsing and Docker image/tag generation utilities.