Log a workout session

Args:
    exercise: Name of the exercise performed
    sets: Number of sets completed
    reps: Number of repetitions per set

Returns:
    Confirmation message with workout details

Calculate total workout volume (weight x sets x reps)

Args:
    weight: Weight used in pounds or kilograms
    sets: Number of sets
    reps: Number of repetitions per set

Returns:
    Dictionary with volume calculation details

Save a workout plan to DynamoDB

Takes the JSON output from workout_plan_prompt and saves it to DynamoDB
following the schema defined in DYNAMODB_DATA_MODEL.md.

This creates all necessary entities:
- WorkoutPlan (plan metadata)
- WeekTemplate (one per week)
- WorkoutSession (one per workout day)
- PlannedExercise (one per exercise)

Args:
    workout_plan_json: JSON string of workout plan (output from workout_plan_prompt)
    user_id: User ID who owns this plan
    plan_id: Optional plan ID (auto-generated UUID if not provided)
    table_name: DynamoDB table name (default: WorkoutPlans)
    region: AWS region (default: us-west-2)

Returns:
    Dictionary with success status and statistics about created entities

Example:
    result = save_workout_plan_to_dynamodb(
        workout_plan_json='{"plan_metadata": {...}, "weeks": [...]}',
        user_id="user_123"
    )

Retrieve a complete workout plan from DynamoDB

Fetches the entire workout plan structure including:
- Plan metadata (name, goal, duration, status, etc.)
- All weeks in the program
- All workout sessions for each week
- All exercises for each workout session

Args:
    user_id: User ID who owns the plan
    plan_id: Unique plan identifier
    table_name: DynamoDB table name (default: WorkoutPlans)
    region: AWS region (default: us-west-2)

Returns:
    Dictionary containing the complete workout plan with plan_metadata and weeks,
    or error information if the plan is not found or retrieval fails

Example:
    result = get_workout_plan_from_dynamodb(
        user_id="user_123",
        plan_id="plan_abc123"
    )

Log a completed workout session to DynamoDB

Records the actual workout performed including session metadata and all exercise sets.
This creates:
- WorkoutLog (session metadata: start/end time, duration, energy level, etc.)
- ExerciseSetLog (one per set performed with weight, reps, RPE, form rating, etc.)

The workout_log_json should contain:
{
    "plan_id": "plan_abc",
    "week_number": 1,
    "day_number": 1,
    "workout_date": "2026-01-06",
    "started_at": "2026-01-06T14:30:00Z",
    "completed_at": "2026-01-06T15:45:00Z",
    "duration_min": 75,
    "perceived_difficulty": 8,
    "energy_level": 7,
    "sleep_quality": 8,
    "pre_workout_nutrition": "protein shake + banana",
    "bodyweight_lbs": 185,
    "status": "completed",
    "exercises": [
        {
            "exercise_id": "bench_press_barbell",
            "exercise_name": "Barbell Bench Press",
            "sets": [
                {
                    "set_number": 1,
                    "set_type": "working",
                    "weight_lbs": 225,
                    "reps_completed": 5,
                    "reps_target": 5,
                    "rpe": 8,
                    "rir": 2,
                    "tempo_actual": "2-0-1-0",
                    "rest_seconds_actual": 180,
                    "form_rating": 9,
                    "notes": "Felt strong",
                    "failed": false,
                    "spotted": false
                }
            ]
        }
    ]
}

Args:
    workout_log_json: JSON string of workout log data
    user_id: User ID who performed the workout
    log_id: Optional log ID (auto-generated UUID if not provided)
    table_name: DynamoDB table name (default: WorkoutPlans)
    region: AWS region (default: us-west-2)

Returns:
    Dictionary with success status and statistics about logged entities

Example:
    result = log_workout_session_to_dynamodb(
        workout_log_json='{"plan_id": "plan_abc", "week_number": 1, ...}',
        user_id="user_123"
    )

Get a list of all exercises with pagination.

Args:
    limit: Maximum number of exercises to return (default: 20, max: 100)
    offset: Number of exercises to skip (default: 0)

Returns:
    A formatted string containing exercise information including name, body parts,
    target muscles, equipment, and instructions.

Get detailed information about a specific exercise by its ID.

Args:
    exercise_id: The unique identifier of the exercise

Returns:
    Detailed exercise information including name, body parts, target muscles,
    equipment, instructions, and GIF URL.

Search for exercises by name or keyword with fuzzy matching.

Args:
    query: Search query (exercise name or keyword)
    limit: Maximum number of exercises to return (default: 20, max: 100)
    offset: Number of exercises to skip (default: 0)
    threshold: Fuzzy match threshold 0.0-1.0 (default: 0.3, lower = more results)

Returns:
    List of exercises matching the search query with relevance scoring.

Get exercises targeting a specific body part.

Args:
    body_part: Body part to filter by (e.g., 'chest', 'back', 'legs', 'shoulders', 'arms')
    limit: Maximum number of exercises to return (default: 20, max: 100)
    offset: Number of exercises to skip (default: 0)

Returns:
    List of exercises for the specified body part.

Get exercises targeting a specific muscle.

Args:
    target: Target muscle to filter by (e.g., 'biceps', 'triceps', 'quads', 'hamstrings')
    limit: Maximum number of exercises to return (default: 20, max: 100)
    offset: Number of exercises to skip (default: 0)

Returns:
    List of exercises targeting the specified muscle.

Get exercises that use specific equipment.

Args:
    equipment: Equipment to filter by (e.g., 'barbell', 'dumbbell', 'cable', 'body weight')
    limit: Maximum number of exercises to return (default: 20, max: 100)
    offset: Number of exercises to skip (default: 0)

Returns:
    List of exercises using the specified equipment.

Get a list of all available body parts in the database.

Returns:
    Comma-separated list of body parts that can be used for filtering.

Get a list of all available target muscles in the database.

Returns:
    Comma-separated list of target muscles that can be used for filtering.

Get a list of all available equipment types in the database.

Returns:
    Comma-separated list of equipment types that can be used for filtering.