`HyperParameterTuningJob.create` rejects tuner tags on Python 3.14

Open Beginner friendly
  • Is something wrong?
#6,554 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
machine-learning

Research direction

Start with the tags annotation on HyperParameterTuningJob.create in the sagemaker-core resources module, and with the Tag objects built in HyperparameterTuner.tune(). The bug is that the unqualified Tag name resolves to the resources model on Python 3.14. Done when a tagged HPO request validates on Python 3.14 and a regression test covering that case passes.

Written by the indexing model from the issue text.

Description

PySDK Version

  • PySDK V2 (2.x)
  • PySDK V3 (3.x)

Describe the bug

Tagged HyperparameterTuner requests fail validation on Python 3.14.
Equivalent requests succeed on Python 3.12.

The tuner creates request tags as sagemaker.core.shapes.Tag.
On Python 3.14, HyperParameterTuningJob.create() resolves its tags
annotation as list[sagemaker.core.resources.Tag].

Both classes have the same key and value fields. However, they are separate
Pydantic models. Pydantic rejects the shapes model instead of converting it to
the generated resource model.

The failure occurs before the SDK calls SageMaker.

This is not a SageMaker v3.28 regression. The behavior also reproduces with the
v3.27 component set on Python 3.14.

To reproduce

Save this script as reproduce.py. It does not call a live AWS service.

import importlib.metadata
import inspect
import sys

from pydantic import TypeAdapter
from sagemaker.core.resources import HyperParameterTuningJob
from sagemaker.core.shapes import Tag

tags_annotation = inspect.signature(
    HyperParameterTuningJob.create
).parameters["tags"].annotation

print("Python:", sys.version)
print("SageMaker:", importlib.metadata.version("sagemaker"))
print("SageMaker Core:", importlib.metadata.version("sagemaker-core"))
print("Resource annotation:", tags_annotation)

validated_tags = TypeAdapter(tags_annotation).validate_python(
    [
        Tag(
            key="project",
            value="hpo-tag-reproduction",
        )
    ]
)

print("Validated tags:", validated_tags)

Run it with Python 3.12:

uvx --python 3.12 --from sagemaker==3.28.0 python reproduce.py

The script succeeds. The annotation resolves to
sagemaker.core.shapes.Tag.

Run it with Python 3.14:

uvx --python 3.14 --from sagemaker==3.28.0 python reproduce.py

The script fails. The annotation resolves to
sagemaker.core.resources.Tag.

The same mismatch occurs during HyperparameterTuner.tune(). The tuner creates
its request tags with this code:

from sagemaker.core.shapes import Tag

tag_objects = [
    Tag(key=boto_tag["Key"], value=boto_tag["Value"])
    for boto_tag in (_to_boto_tag(tag) for tag in self.tags)
]

Expected behavior

HyperParameterTuningJob.create() must accept the tag model produced by
HyperparameterTuner on every supported Python version.

Screenshots or logs

Python 3.14 produces this error:

Resource annotation: typing.List[sagemaker.core.resources.Tag] | None
Traceback (most recent call last):
  ...
pydantic_core._pydantic_core.ValidationError:
1 validation error for nullable[list[Tag]]
0
  Input should be a valid dictionary or instance of Tag
  [type=model_type,
   input_value=Tag(key='project', value='hpo-tag-reproduction'),
   input_type=Tag]

System information

  • SageMaker Python SDK version: 3.28.0
  • SageMaker Core version: 2.28.0
  • SageMaker Train version: 1.28.0
  • Framework name (eg. PyTorch) or algorithm (eg. KMeans): Framework-independent
  • Framework version: Not applicable
  • Python version: 3.14
  • CPU or GPU: CPU
  • Custom Docker image (Y/N): Reproduces before image selection

Additional context

Python 3.14 uses deferred annotation evaluation. The unqualified Tag name
resolves after sagemaker.core.resources.Tag exists in the module.

Earlier Python versions capture the imported sagemaker.core.shapes.Tag when
the function is defined.

A stable fix can import the public shape with an unambiguous alias:

from sagemaker.core.shapes import Tag as ShapeTag

def create(
    # ...
    tags: list[ShapeTag] | None = None,
):
    ...

Tests must exercise tagged HPO request validation on Python 3.14.

Dominant language
Python
Stars
2.3k
Forks
1.3k
Avg merge
1d 18h
Merged PRs (30d)
65

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from aws/sagemaker-python-sdk

All issues in aws/sagemaker-python-sdk

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.