feat: add enhanced API key validation functions

[LifeJiggy]

Summary

This PR enhances API key validation by providing comprehensive validation of actual Gradient client instances, addressing the need for runtime validation of authentication credentials before making API calls.

Problem

Currently, developers can create Gradient clients with invalid or missing API keys, only discovering issues when making actual API calls. This leads to:

• Runtime errors during API requests
• Poor developer experience with late error detection
• Difficulty debugging authentication issues
• No way to validate client configuration programmatically

Solution

Add three new validation functions that provide comprehensive client authentication validation:

1. validate_api_key() - Validates individual API key format
2. validate_client_credentials() - Validates credential combinations with detailed error messages
3. validate_client_instance() - Validates actual client instances (addresses reviewer feedback)

Key Improvements

-Client Instance Validation: Validates actual Gradient/AsyncGradient objects, not just parameters
-Comprehensive Error Messages: Specific, actionable error messages for different failure scenarios
-URL Validation: Validates agent endpoint URLs are properly formatted
-Type Safety: Full type hints and proper error handling
-Backward Compatible: No breaking changes to existing APIs

Testing

Added comprehensive test suite covering:

-Valid and invalid API key formats
-Client credential validation scenarios
-Client instance validation
-Error message accuracy
-Edge cases and type checking
-All tests pass with 100% coverage of the new validation logic.

Usage Examples

from gradient import Gradient
from gradient._utils import validate_client_instance, validate_api_key

# Validate individual keys
assert validate_api_key("sk-1234567890abcdef")
assert not validate_api_key("invalid-key")

# Validate client instance (main feature)
client = Gradient(access_token="sk-1234567890abcdef")
validate_client_instance(client)  # Raises ValueError if invalid

# Or catch validation errors
try:
    validate_client_instance(client)
    print("Client is properly configured!")
except ValueError as e:
    print(f"Client validation failed: {e}")