garmin-training-toolkit-sdk 0.7.0

A robust, type-safe Python SDK for Garmin Connect data extraction.

Garmin Training Toolkit SDK

A robust, type-safe Python SDK for extracting biometric data and telemetry from Garmin Connect, optimized for autonomous agents and LLM tool-calling.

Architecture: LLM-Native & Vendor-Agnostic

The SDK has been refactored to prioritize:

1. Semantic Naming: No more cryptic Garmin fields. We use min_target, max_target, and target_type.
2. Provider Pattern: Logic is decoupled from Garmin-specific APIs. You can now use a standardized BaseBiometricProvider interface.
3. Agent-First Schema: Pydantic models include exhaustive descriptions and Literal types, allowing LLMs to understand the tool requirements with 100% accuracy from the JSON schema alone.

Installation

This project uses uv for dependency management.

# In your consumer project:
uv add git+https://github.com/restrok/garmin-training-toolkit-sdk.git#subdirectory=garmin_toolkit

Quick Start

1. Standardized Provider Interface

The recommended way to use the SDK is via the GarminProvider.

from datetime import date
from garmin_training_toolkit_sdk.core.garmin import GarminProvider

# 1. Initialize (automatically finds local tokens)
provider = GarminProvider()
# 2. Fetch Activities (Returns vendor-agnostic Protocol models)
activities = provider.get_activities(date(2026, 4, 1), date(2026, 4, 30))
latest = activities[0]
print(f"Activity: {latest.name} | Distance: {latest.distance_m}m")

# 3. Calendar Range Queries (New)
items = provider.get_calendar_range(date(2026, 5, 25), date(2026, 6, 5))
print(f"Found {len(items)} scheduled items across month boundaries.")

# 4. Wellness Metrics (New)
sleep = provider.get_sleep_history(date(2026, 4, 1), date(2026, 4, 7))
hrv = provider.get_hrv_history(date(2026, 4, 1), date(2026, 4, 7))
profile = provider.get_user_profile()

# 5. Workout Introspection (New)
workouts = provider.get_workout_templates()
for w in workouts:
    print(f"Template: {w.workout_name} ({w.sport_type})")

# 6. Get Telemetry
telemetry = provider.get_telemetry(latest.id)

Key Features

🛡️ Robust Authentication & Self-Healing

The SDK now handles OAuth scopes more comprehensively (including USER_PROFILE) and features automated self-healing. If a 401 Unauthorized is encountered on a non-critical endpoint, the provider automatically attempts a token refresh and retries the operation seamlessly. This protection now covers all activity, calendar, and wellness data fetches.

📅 Date-Based Query Standardization

Methods like get_scheduled_workouts have been refactored to accept standard date objects. The SDK handles all internal year/month pagination and boundary logic, including the new get_calendar_range method which deduplicates items across month boundaries.

🧩 Provider-Agnostic Interface

The BaseBiometricProvider now includes standardized methods for:

• Deletion: unschedule_workout and delete_workout_template.
• Wellness: get_sleep_history, get_hrv_history, and get_user_profile. This allows higher-level coaching and ETL logic to remain completely brand-agnostic.

🧪 Agent Tool Compatibility

Tools generated by the ToolFactory now include a .run() method, ensuring full compatibility with LangChain StructuredTool expectations and making them directly callable for internal execution. The factory now exposes 10 core tools covering activities, workouts, and biometrics.

Tool Factory (For AI Agents)

2. LLM-Native Workouts (Agent Friendly)

Agents can create workouts using semantic naming or high-level helpers.

from garmin_training_toolkit_sdk.protocol.workouts import create_simple_hr_workout

# High-level helper for Agents
workout = create_simple_hr_workout(
    name="Z2 Recovery Run",
    date="2026-05-01",
    bpm_min=135,
    bpm_max=145,
    duration_mins=45
)

# Upload via the provider
report = provider.upload_training_plan(workout)
print(f"Status: {report.message}")

Tool Factory (For AI Agents)

If you are building an AI Agent (LangChain, AutoGPT, etc.), you can use the ToolFactory to generate a standardized set of tools from any provider.

from garmin_training_toolkit_sdk.core.factory import ToolFactory
from garmin_training_toolkit_sdk.core.garmin import GarminProvider

provider = GarminProvider()
tools = ToolFactory.create_tools(provider)

# These tools have semantic descriptions that LLMs love:
# - get_activities
# - get_telemetry
# - upload_training_plan

Directory Structure

• core/: Provider implementations (Garmin, etc.) and the Tool Factory.
• protocol/: Vendor-agnostic Pydantic models (Activity, Telemetry, Workout).
• extractors/: Low-level data extraction logic.
• uploaders/: Logic for calendar and workout management.

Testing & Mocks

The SDK includes a MockGarminClient in testing/mock.py to allow consumers to test their pipelines without hitting Garmin's production APIs.

from garmin_training_toolkit_sdk.testing.mock import MockGarminClient
# Use in your unit tests to avoid rate limits