{"id":9289,"library":"sagemaker-experiments","title":"SageMaker Experiments SDK","description":"sagemaker-experiments is an open-source Python library from AWS for experiment tracking within Amazon SageMaker jobs and notebooks. It allows users to create, manage, and query machine learning experiments, trials, and trial components to track model parameters, metrics, and artifacts. The library maintains an active release cadence, with frequent minor updates.","status":"active","version":"0.1.45","language":"en","source_language":"en","source_url":"https://github.com/aws/sagemaker-experiment-tracking/","tags":["aws","sagemaker","mlops","experiment-tracking","machine-learning"],"install":[{"cmd":"pip install sagemaker-experiments","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core SageMaker SDK for interacting with AWS SageMaker services.","package":"sagemaker","optional":false},{"reason":"AWS SDK for Python, underlying client for SageMaker API calls.","package":"boto3","optional":false},{"reason":"Optional dependency, required if logging scikit-learn specific artifacts/metrics (note: replaced 'sklearn' in v0.1.42).","package":"scikit-learn","optional":true}],"imports":[{"symbol":"Experiment","correct":"from sagemaker.experiments import Experiment"},{"symbol":"Trial","correct":"from sagemaker.experiments import Trial"},{"symbol":"Tracker","correct":"from sagemaker.experiments.tracker import Tracker"}],"quickstart":{"code":"import os\nimport sagemaker\nfrom sagemaker.experiments import Experiment, Trial\nfrom sagemaker.experiments.tracker import Tracker\n\n# Ensure a SageMaker session is available. In a SageMaker Studio or Job,\n# a session is usually automatically configured.\n# For local execution, ensure AWS credentials and region are set up (e.g., via environment vars).\ntry:\n    sess = sagemaker.Session()\nexcept Exception:\n    # Fallback for local execution outside a SageMaker context if default fails\n    import boto3\n    print(\"Creating sagemaker.Session with boto3.Session for local execution.\")\n    sess = sagemaker.Session(boto3.Session(region_name=os.environ.get(\"AWS_REGION\", \"us-east-1\")))\n\nexperiment_name = f\"my-quickstart-experiment-{os.getpid()}\"\ntrial_name = f\"my-quickstart-trial-{os.getpid()}\"\n\n# 1. Create an Experiment\n# Using .create() ensures a new experiment; .load() would retrieve an existing one.\nmy_experiment = Experiment.create(\n    experiment_name=experiment_name,\n    description=\"A simple quickstart experiment for sagemaker-experiments\",\n    sagemaker_session=sess\n)\nprint(f\"Created Experiment: {my_experiment.experiment_name}\")\n\n# 2. Create a Trial within the Experiment\nmy_trial = Trial.create(\n    trial_name=trial_name,\n    experiment_name=experiment_name,\n    sagemaker_session=sess\n)\nprint(f\"Created Trial: {my_trial.trial_name}\")\n\n# 3. Use a Tracker to log parameters and metrics (e.g., simulating a training run)\nwith Tracker.create(display_name=\"TrainingJobComponent\", sagemaker_session=sess) as tracker:\n    tracker.log_parameters({\"learning_rate\": 0.01, \"epochs\": 10, \"optimizer\": \"Adam\"})\n    tracker.log_metrics({\"accuracy\": 0.85, \"loss\": 0.15, \"f1_score\": 0.82})\n    print(f\"Logged data to TrialComponent: {tracker.trial_component.trial_component_name}\")\n    \n    # Associate the tracker's automatically created trial component with our trial\n    my_trial.add_trial_component(tracker.trial_component)\n\nprint(\"Experiment, Trial, and TrialComponent created and data logged.\")\nprint(\"You can view these in SageMaker Studio under the Experiments tab.\")\n\n# Optional: Clean up created resources (uncomment to enable)\n# print(\"Cleaning up resources...\")\n# my_trial.delete_all_trial_components()\n# my_trial.delete()\n# my_experiment.delete()\n# print(\"Cleanup complete.\")","lang":"python","description":"This quickstart demonstrates how to initialize a SageMaker session, create an `Experiment` and `Trial`, and then use a `Tracker` to log parameters and metrics. It includes robust session handling for both SageMaker environments and local execution."},"warnings":[{"fix":"Ensure `scikit-learn` is installed in your environment: `pip install scikit-learn`. Update any direct `import sklearn` statements to `import scikit-learn` if applicable (though typically you import submodules like `from sklearn.ensemble import RandomForestClassifier`).","message":"The `sklearn` dependency was renamed to `scikit-learn` in `v0.1.42`. Projects directly depending on `sklearn` might experience `ModuleNotFoundError` if `scikit-learn` is not installed.","severity":"breaking","affected_versions":"v0.1.42 and later"},{"fix":"Upgrade your Python environment to 3.7 or newer. Recommended versions are Python 3.9, 3.10, or 3.11 for broader compatibility and active support.","message":"Support for Python 3.6 was officially dropped in `v0.1.42`. Users running `sagemaker-experiments` on Python 3.6 will encounter compatibility issues.","severity":"breaking","affected_versions":"v0.1.42 and later"},{"fix":"After creating your `Trial` and using `Tracker.create()`, explicitly associate the `TrialComponent`: `my_trial.add_trial_component(tracker.trial_component)`.","message":"When `Tracker.create()` is used outside of a SageMaker Training Job, it automatically creates a new `TrialComponent`. To associate this component with a specific `Trial` created manually (e.g., using `Trial.create()`), you must explicitly add it.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `sagemaker-experiments v0.1.44` or newer. If upgrading is not immediately possible, ensure that all SageMaker job names and trial component names use consistent casing, preferably lowercase, to avoid this specific issue.","message":"A bug prior to `v0.1.44` caused issues loading trial components for jobs with mixed-case names. This could lead to difficulties in retrieving or visualizing experiment data.","severity":"gotcha","affected_versions":"Prior to v0.1.44"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library using `pip install sagemaker-experiments`. Ensure your import statements are correct, typically `from sagemaker.experiments import Experiment`.","cause":"The `sagemaker-experiments` library is not installed, or the import path is incorrect (e.g., trying `import sagemaker_experiments`).","error":"ModuleNotFoundError: No module named 'sagemaker.experiments'"},{"fix":"Ensure `boto3` is configured with valid AWS credentials and a region (e.g., via environment variables, `~/.aws/credentials`, or `~/.aws/config`). When running locally, explicitly create a session: `import boto3; sess = sagemaker.Session(boto3.Session(region_name='your-region'))`.","cause":"The code is being run outside a SageMaker Studio notebook or training job context without an explicit `sagemaker.Session` configured, or `boto3` credentials/region are not set up for local execution.","error":"AttributeError: 'Session' object has no attribute 'sagemaker_client' (or similar 'No default SageMaker session found' messages)"},{"fix":"Choose a unique name for your experiment (e.g., by appending a timestamp or process ID). If you intend to work with an existing experiment, use `Experiment.load(experiment_name='your-experiment-name', sagemaker_session=sess)` instead of `Experiment.create()`.","cause":"You are attempting to create an experiment with a name that is already in use in your AWS account and region.","error":"An error occurred (ValidationException) when calling the CreateExperiment operation: The Experiment with name '...' already exists."},{"fix":"Ensure that parameters and metrics are provided as flat dictionaries with scalar values. For complex objects, serialize them to strings (e.g., JSON) or store them as artifacts in S3 and log their S3 URIs.","cause":"The `tracker.log_parameters()` and `tracker.log_metrics()` methods expect dictionary inputs where values are simple types (numbers, strings, booleans). Attempting to log complex objects directly will fail.","error":"TypeError: 'TrialComponent' object is not iterable (or similar type errors when logging)"}]}