feat: Add smart base image detection from pyproject.toml

- Auto-detect Python version from requires-python field
- Base images now always required (ensures Python runtime)
- Default to python:X.Y-slim based on detected version
- Users can still override with --base-image flag
- Update all documentation and examples
- Bump version to 0.3.0

Breaking change: Base images are no longer optional, but auto-detection
maintains backward compatibility for projects specifying requires-python.

Author: spboyer

.github/copilot-instructions.md

@@ -20,9 +20,9 @@ cli.py (entry point)
 
 ### Key Architectural Decisions
 
-1. **No Base Image Layering (Yet)**: Currently only creates application layers, doesn't pull/layer base images like `python:3.11-slim`. The `base_image` field in `BuildConfig` is defined but not used—this is a known limitation.
+1. **Smart Base Image Selection**: Auto-detects Python version from `requires-python` in `pyproject.toml` and constructs base image name (e.g., `>=3.11` → `python:3.11-slim`). Users can override with `--base-image` flag. Base images are always required—every build pulls and layers on a Python runtime.
 
-2. **Single Layer Output**: Creates one tar layer with all app files, writes to `dist/image/blobs/sha256/<digest>`. The OCI manifest + config are written to `dist/image/`.
+2. **Multi-Layer Output**: Creates base image layers + optional dependency layer + application layer. All layers are written to `dist/image/blobs/sha256/<digest>`. The OCI manifest + config are written to `dist/image/`.
 
 3. **Entrypoint Auto-Detection**: `project.py` reads `pyproject.toml` → looks for `[project.scripts]` → converts first script to Python module invocation. Falls back to `python -m app` if nothing found.
 
@@ -117,12 +117,11 @@ if child.is_file() and not any(child.match(p) for p in exclude):
 
 ## Known Limitations (Do Not "Fix" Without Discussion)
 
-1. **No base image support**: Doesn't download/layer Python runtime. Output is app-only.
-2. **No registry push**: No code to push to Docker Hub/GitHub Container Registry.
-3. **No dependency installation**: Doesn't run `pip install`. Expects dependencies already in context.
-4. **Single architecture**: Hard-coded to `amd64`/`linux` in `builder.py`.
+1. **Single architecture support**: Metadata supports multi-arch but no actual cross-compilation yet.
+2. **Limited framework detection**: Supports FastAPI, Flask, Django only (easy to extend).
+3. **SBOM scope**: Python packages only; doesn't parse OS packages from base images.
 
-These are intentional scope limitations for the experiment phase.
+These are intentional scope limitations for the current phase.
 
 ## Dependencies
 

ARCHITECTURE.md

@@ -166,11 +166,31 @@ class ImageBuilder:
 
 ### 3. Project Layer (`project.py`)
 
-**Purpose**: Introspect Python projects to extract metadata, entry points, and structure.
+**Purpose**: Introspect Python projects to extract metadata, entry points, structure, and Python version.
 
 **Key Functions**:
 
 ```python
+def detect_python_version(context_dir) -> str:
+    """
+    Detect Python version from pyproject.toml requires-python field.
+    
+    Extracts version from patterns like:
+    - ">=3.11" → "3.11"
+    - "^3.12" → "3.12"
+    - "~=3.10" → "3.10"
+    
+    Returns:
+        Python version string (e.g., "3.11"), defaults to "3.11" if not found
+    """
+    pyproject = parse_pyproject_toml(context_dir / "pyproject.toml")
+    requires_py = pyproject.get("project", {}).get("requires-python")
+    if requires_py:
+        match = re.search(r'(\d+\.\d+)', requires_py)
+        if match:
+            return match.group(1)
+    return "3.11"
+
 def discover_project(context_path: Path) -> ProjectMetadata:
     """
     Discover Python project structure and metadata.
@@ -484,7 +504,7 @@ class BuildConfig:
     workdir: str = "/app"
     env: dict[str, str] = field(default_factory=dict)
     include_paths: list[str] = field(default_factory=list)
-    base_image: str | None = None  # Phase 2
+    base_image: str = "python:3.11-slim"  # Auto-detected from requires-python
     registry: str | None = None
     use_cache: bool = True
 
@@ -659,11 +679,17 @@ def discover_project(context_path: Path,
 
 **Approach**: Implement OCI spec directly using Python stdlib + HTTP requests.
 
-### Why Single Layer (Phase 0)?
+### Why Smart Base Image Detection?
+
+**Rationale**: Simplify user experience by automatically selecting the correct Python base image from project metadata.
 
-**Rationale**: Simplify initial implementation, prove feasibility.
+**Approach**: Parse `requires-python` from `pyproject.toml` and construct base image name (e.g., `>=3.11` → `python:3.11-slim`).
 
-**Future**: Phase 2 adds multi-layer support (base + deps + app).
+**Benefits**:
+- Zero configuration for common cases
+- Always includes Python runtime (no invalid app-only images)
+- Respects project's Python version requirements
+- Users can still override with `--base-image` flag
 
 ### Why Dataclasses Over Dicts?
 

README.md

@@ -38,13 +38,13 @@ pip install -e .
 ### Build Your First Image
 
 ```bash
-# Simple build (auto-detects everything)
+# Simple build (auto-detects Python version and base image)
 pycontainer build --tag myapp:latest
 
-# Build on a base image with dependencies
+# Build with custom base image and dependencies
 pycontainer build \
   --tag myapp:v1 \
-  --base-image python:3.11-slim \
+  --base-image python:3.12-slim \
   --include-deps
 
 # Build FastAPI app (auto-detected, entrypoint configured)
@@ -102,7 +102,8 @@ dist/image/
 - ✅ **Fast incremental builds** — Reuses unchanged layers from cache
 
 **Base Images & Dependencies** (Phase 2):
-- ✅ **Base image support** — Build on top of `python:3.11-slim`, distroless, etc.
+- ✅ **Smart base image detection** — Auto-selects Python base image from `requires-python` in pyproject.toml
+- ✅ **Base image support** — Build on top of `python:3.11-slim`, `python:3.12-slim`, distroless, etc.
 - ✅ **Layer merging** — Combines base image layers with application layers
 - ✅ **Config inheritance** — Merges env vars, labels, working dir from base images
 - ✅ **Dependency packaging** — Include pip packages from venv or requirements.txt
@@ -235,6 +236,7 @@ Install from VS Code Marketplace or command palette:
 
 By default, `pycontainer` auto-detects:
 
+- **Base image**: Python version from `requires-python` in `pyproject.toml` (e.g., `>=3.11` → `python:3.11-slim`)
 - **Entry point**: First `[project.scripts]` entry in `pyproject.toml`
 - **Include paths**: `src/`, `app/`, or `<package>/` dirs + `pyproject.toml`, `requirements.txt`
 - **Working directory**: `/app/`
@@ -261,7 +263,7 @@ pycontainer build \
 ```
 
 **Base Image & Dependencies**:
-- `--base-image IMAGE` — Base image to build on (e.g., `python:3.11-slim`)
+- `--base-image IMAGE` — Base image to build on (auto-detected from `requires-python` if not specified, e.g., `python:3.11-slim`)
 - `--include-deps` — Package dependencies from venv or requirements.txt
 
 **Caching Options**:
@@ -290,7 +292,7 @@ from pycontainer.builder import ImageBuilder
 config = BuildConfig(
     tag="myapp:latest",
     context_path=".",
-    base_image="python:3.11-slim",
+    base_image="python:3.11-slim",  # Optional: auto-detected if omitted
     include_deps=True,
     workdir="/app",
     env={"DEBUG": "false", "ENV": "production"},

docs/azd-integration.md

@@ -55,12 +55,13 @@ services:
         run: |
           pycontainer build \
             --tag ${SERVICE_IMAGE_NAME}:${SERVICE_IMAGE_TAG} \
-            --base-image python:3.11-slim \
             --include-deps \
             --context ${SERVICE_PATH} \
             --push
 ```
 
+> **Note**: The `--base-image` flag is optional. pycontainer-build will auto-detect the Python version from your `pyproject.toml` (`requires-python` field) and use the appropriate base image (e.g., `python:3.11-slim`). You can override this by explicitly setting `--base-image python:3.12-slim` or any custom base image.
+
 ### 3. Deploy
 
 ```bash

docs/local-development.md

@@ -72,10 +72,15 @@ By default, images are created at:
 ### With Base Image & Dependencies
 
 ```bash
-# Build on a Python base image
+# Build with auto-detected Python base image
 pycontainer build \
   --tag myapp:latest \
-  --base-image python:3.11-slim \
+  --include-deps
+
+# Or explicitly specify a base image
+pycontainer build \
+  --tag myapp:latest \
+  --base-image python:3.12-slim \
   --include-deps
 
 # This will:

examples/fastapi-app/README.md

@@ -8,7 +8,11 @@ This is a sample FastAPI application demonstrating all pycontainer-build integra
 
 ```bash
 cd examples/fastapi-app
+# Base image auto-detected from pyproject.toml (requires-python: ">=3.11")
 pycontainer build --tag fastapi-demo:latest --include-deps
+
+# Or with custom base image
+pycontainer build --tag fastapi-demo:latest --base-image python:3.12-slim --include-deps
 ```
 
 ### Build with Poetry Plugin
@@ -124,12 +128,13 @@ This example includes configuration for all integrations:
 
 ## Features Demonstrated
 
-- ✅ Framework auto-detection (FastAPI automatically configured)
-- ✅ Entry point auto-detection from pyproject.toml
-- ✅ Dependency packaging with `--include-deps`
-- ✅ Environment variable configuration
-- ✅ OCI label metadata
-- ✅ Multiple integration methods
+- ✅ **Base image auto-detection** - Python version detected from `requires-python` in pyproject.toml
+- ✅ **Framework auto-detection** - FastAPI automatically configured with proper entrypoint
+- ✅ **Entry point auto-detection** - Reads `[project.scripts]` from pyproject.toml
+- ✅ **Dependency packaging** - Include pip packages with `--include-deps`
+- ✅ **Environment variable configuration** - Custom env vars for production
+- ✅ **OCI label metadata** - Maintainer, description, and custom labels
+- ✅ **Multiple integration methods** - CLI, Poetry, Hatch, VS Code, GitHub Actions, azd
 
 ## Learn More
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pycontainer-build"
-version = "0.2.1"
+version = "0.3.0"
 description = "Experimental .NET-style native OCI image builder for Python projects (no Docker daemon, no Dockerfile)."
 readme = "README.md"
 requires-python = ">=3.11"

src/pycontainer/builder.py

@@ -34,7 +34,7 @@ def build(self):
         layers_dir=ensure_dir(blobs/'sha256')
         refs_dir=ensure_dir(output/'refs'/'tags')
 
-        base_layers, base_config = self._pull_base_image(layers_dir) if self.config.base_image else ([], None)
+        base_layers, base_config = self._pull_base_image(layers_dir)
 
         entry = self.config.entrypoint or detect_entrypoint(self.config.context_dir)
         include = self.config.include_paths or default_include_paths(self.config.context_dir)
@@ -157,7 +157,7 @@ def push(self, registry_url: Optional[str]=None, auth_token: Optional[str]=None,
     def _show_build_plan(self):
         """Display build plan for dry-run mode."""
         print(f"Build Plan for {self.config.tag}:")
-        print(f"  Base Image: {self.config.base_image or 'scratch'}")
+        print(f"  Base Image: {self.config.base_image}")
         print(f"  Context: {self.config.context_dir}")
         print(f"  Working Dir: {self.config.workdir}")
         print(f"  Entrypoint: {' '.join(self.config.entrypoint or ['<auto-detect>'])}")

src/pycontainer/cli.py

@@ -3,14 +3,15 @@
 from .config import BuildConfig
 from .builder import ImageBuilder
 from .config_loader import config_from_file
+from .project import detect_python_version
 
 def main():
     parser=argparse.ArgumentParser()
     sub=parser.add_subparsers(dest="cmd",required=True)
     b=sub.add_parser("build")
     b.add_argument("--config","-c",help="Path to pycontainer.toml config file")
     b.add_argument("--tag")
-    b.add_argument("--base-image",help="Base image to layer on (e.g., python:3.11-slim)")
+    b.add_argument("--base-image",help="Base image to layer on (auto-detected from requires-python if not specified)")
     b.add_argument("--context",default=".")
     b.add_argument("--push",action="store_true",help="Push image to registry after build")
     b.add_argument("--registry",help="Override registry from tag (e.g., ghcr.io/user/repo:v1)")
@@ -52,9 +53,13 @@ def main():
         cfg=config_from_file(Path(args.config), cli_overrides)
     else:
         tag=args.tag or "local/test:latest"
+        base_img=args.base_image
+        if not base_img:
+            py_ver=detect_python_version(args.context)
+            base_img=f"python:{py_ver}-slim"
         cfg=BuildConfig(
             tag=tag, 
-            base_image=args.base_image,
+            base_image=base_img,
             context_dir=args.context,
             use_cache=not args.no_cache,
             cache_dir=args.cache_dir,

src/pycontainer/config.py

@@ -4,7 +4,7 @@
 @dataclass
 class BuildConfig:
     tag: str = "local/test:latest"
-    base_image: Optional[str] = None
+    base_image: str = "python:3.11-slim"
     context_dir: str = "."
     workdir: str = "/app"
     entrypoint: Optional[List[str]] = None