0
# Client Management
1

2
Core client classes for synchronous and asynchronous API access to Aleph Alpha's language model services. Provides connection management, authentication, retry logic, and comprehensive error handling.
3

4
## Capabilities
5

6
### Synchronous Client
7

8
The main client class for synchronous API operations with built-in retry logic and connection pooling.
9

10
```python { .api }
11
class Client:
12
    def __init__(
13
        self,
14
        token: str,
15
        host: str = "https://api.aleph-alpha.com",
16
        hosting: Optional[str] = None,
17
        request_timeout_seconds: int = 305,
18
        total_retries: int = 8,
19
        nice: bool = False,
20
        verify_ssl: bool = True,
21
        tags: Optional[Sequence[str]] = None,
22
        pool_size: int = 10
23
    ):
24
        """
25
        Initialize synchronous Aleph Alpha client.
26
        
27
        Parameters:
28
        - token: API authentication token
29
        - host: API endpoint URL
30
        - hosting: Datacenter preference ("aleph-alpha" or None)
31
        - request_timeout_seconds: Timeout for individual requests
32
        - total_retries: Number of retry attempts for failed requests
33
        - nice: Deprioritize requests for background processing
34
        - verify_ssl: Enable SSL certificate verification
35
        - tags: Internal tagging for request tracking
36
        - pool_size: Connection pool size for HTTP requests
37
        """
38

39
    def validate_version(self) -> None:
40
        """Validate API version compatibility."""
41

42
    def get_version(self) -> str:
43
        """Get current API version."""
44

45
    def models(self) -> List[Mapping[str, Any]]:
46
        """List available models and their capabilities."""
47
        
48
    def tokenizer(self, model: str) -> Tokenizer:
49
        """Get tokenizer instance for specified model."""
50
```
51

52
### Asynchronous Client  
53

54
Asynchronous client implementation with context manager support and enhanced streaming capabilities.
55

56
```python { .api }
57
class AsyncClient:
58
    def __init__(
59
        self,
60
        token: str,
61
        host: str = "https://api.aleph-alpha.com", 
62
        hosting: Optional[str] = None,
63
        request_timeout_seconds: int = 305,
64
        total_retries: int = 8,
65
        nice: bool = False,
66
        verify_ssl: bool = True,
67
        tags: Optional[Sequence[str]] = None
68
    ):
69
        """
70
        Initialize asynchronous Aleph Alpha client.
71
        
72
        Parameters: Same as Client except pool_size (managed internally)
73
        """
74

75
    async def close(self) -> None:
76
        """Close client session and cleanup resources."""
77

78
    async def validate_version(self) -> None:
79
        """Validate API version compatibility (async)."""
80

81
    async def get_version(self) -> str:
82
        """Get current API version (async)."""
83

84
    async def models(self) -> List[Mapping[str, Any]]:
85
        """List available models and their capabilities (async)."""
86
        
87
    async def tokenizer(self, model: str) -> Tokenizer:
88
        """Get tokenizer instance for specified model (async)."""
89
```
90

91
### Error Handling
92

93
Custom exception classes for handling API-specific error conditions.
94

95
```python { .api }
96
class QuotaError(Exception):
97
    """Raised when API quota is exceeded (HTTP 402)."""
98

99
class BusyError(Exception):
100
    """Raised when service is temporarily unavailable (HTTP 503)."""
101
```
102

103
### Usage Examples
104

105
Basic client initialization and usage patterns:
106

107
```python
108
from aleph_alpha_client import Client, AsyncClient, QuotaError, BusyError
109

110
# Synchronous client
111
client = Client(token="your-api-token")
112

113
try:
114
    # Check available models
115
    models = client.models()
116
    print(f"Available models: {[m['name'] for m in models]}")
117
    
118
    # Validate API compatibility
119
    client.validate_version()
120
    
121
except QuotaError:
122
    print("API quota exceeded")
123
except BusyError:
124
    print("Service temporarily unavailable")
125

126
# Asynchronous client with context manager
127
import asyncio
128

129
async def main():
130
    async with AsyncClient(token="your-api-token") as client:
131
        try:
132
            models = await client.models()
133
            print(f"Available models: {[m['name'] for m in models]}")
134
        except QuotaError:
135
            print("API quota exceeded")
136
        except BusyError:
137
            print("Service temporarily unavailable")
138

139
asyncio.run(main())
140

141
# Client with custom configuration
142
client = Client(
143
    token="your-api-token",
144
    host="https://api.aleph-alpha.com",
145
    request_timeout_seconds=120,  # 2 minute timeout
146
    total_retries=5,              # Fewer retries
147
    nice=True,                    # Background processing priority
148
    verify_ssl=True               # SSL verification enabled
149
)
150
```