0
# Types and Configuration
1

2
Comprehensive type system, exception handling, and configuration utilities. Includes Pydantic models for all API responses, TypedDict parameter classes, complete exception hierarchy, and utility functions for file handling and configuration.
3

4
## Capabilities
5

6
### Core Base Types
7

8
Foundation classes and types used throughout the SDK for type safety and consistency.
9

10
```python { .api }
11
class BaseModel:
12
    """
13
    Base Pydantic model class for all API response objects.
14
    
15
    Provides JSON serialization, validation, and type coercion for all
16
    response models in the SDK.
17
    """
18

19
class NoneType:
20
    """Type annotation helper for None values."""
21

22
class NotGiven:
23
    """
24
    Sentinel type for optional parameters that have not been provided.
25
    
26
    Used to distinguish between None (explicit null value) and 
27
    unset parameters in API calls.
28
    """
29

30
NOT_GIVEN: NotGiven
31
"""Sentinel instance for unset parameters."""
32

33
class Omit:
34
    """
35
    Type utility for omitting fields from TypedDicts.
36
    
37
    Used in type annotations to indicate fields that should be
38
    excluded from certain operations.
39
    """
40
```
41

42
### Configuration Types
43

44
Type aliases and configuration classes for client and request configuration.
45

46
```python { .api }
47
# Timeout configuration
48
Timeout: TypeAlias = Union[float, httpx.Timeout, None]
49
"""Type alias for timeout values - can be float (seconds), httpx.Timeout object, or None."""
50

51
# Transport configuration  
52
Transport: TypeAlias = httpx.HTTPTransport
53
"""Type alias for HTTP transport configuration."""
54

55
# Proxy configuration
56
ProxiesTypes: TypeAlias = Union[str, httpx.Proxy, Dict[str, Union[str, httpx.Proxy]]]
57
"""Type alias for proxy configurations - string URL, httpx.Proxy object, or mapping."""
58

59
# Request options
60
RequestOptions: TypeAlias = Dict[str, Any]
61
"""Type alias for per-request configuration options."""
62
```
63

64
### Exception Hierarchy
65

66
Complete exception class hierarchy covering all possible error conditions from API interactions.
67

68
```python { .api }
69
class CerebrasError(Exception):
70
    """Base exception class for all SDK errors."""
71

72
class APIError(CerebrasError):
73
    """
74
    Base class for API-related errors.
75
    
76
    Attributes:
77
    - message: Error message describing the issue
78
    - request: The httpx.Request that caused the error
79
    - body: The API response body (if available)
80
    """
81
    message: str
82
    request: httpx.Request
83
    body: object | None
84

85
class APIStatusError(APIError):
86
    """
87
    Base class for HTTP status code errors.
88
    
89
    Raised when the API returns a non-2xx status code.
90
    """
91
    status_code: int
92
    response: httpx.Response
93

94
class BadRequestError(APIStatusError):
95
    """HTTP 400 Bad Request error."""
96

97
class AuthenticationError(APIStatusError):
98
    """HTTP 401 Unauthorized error - invalid API key or authentication."""
99

100
class PermissionDeniedError(APIStatusError):
101
    """HTTP 403 Forbidden error - insufficient permissions."""
102

103
class NotFoundError(APIStatusError):
104
    """HTTP 404 Not Found error - resource does not exist."""
105

106
class ConflictError(APIStatusError):
107
    """HTTP 409 Conflict error - request conflicts with current state."""
108

109
class UnprocessableEntityError(APIStatusError):
110
    """HTTP 422 Unprocessable Entity error - validation error."""
111

112
class RateLimitError(APIStatusError):
113
    """HTTP 429 Too Many Requests error - rate limit exceeded."""
114

115
class InternalServerError(APIStatusError):
116
    """HTTP 500 Internal Server Error - server-side error."""
117

118
class APIConnectionError(APIError):
119
    """
120
    Network connection error.
121
    
122
    Raised when unable to connect to the API due to network issues.
123
    """
124

125
class APITimeoutError(APIError):
126
    """
127
    Request timeout error.
128
    
129
    Raised when a request times out before receiving a response.
130
    """
131

132
class APIResponseValidationError(APIError):
133
    """
134
    Response validation error.
135
    
136
    Raised when the API response does not match the expected schema.
137
    """
138
```
139

140
### Streaming Classes
141

142
Classes for handling streaming responses and real-time data processing.
143

144
```python { .api }
145
class Stream:
146
    """
147
    Synchronous streaming response handler.
148
    
149
    Provides iteration interface for processing streaming API responses
150
    in real-time as data arrives from the server.
151
    """
152
    def __iter__(self) -> Iterator[Any]: ...
153
    def __next__(self) -> Any: ...
154

155
class AsyncStream:
156
    """
157
    Asynchronous streaming response handler.
158
    
159
    Async version of Stream for use with async/await patterns.
160
    """
161
    def __aiter__(self) -> AsyncIterator[Any]: ...
162
    async def __anext__(self) -> Any: ...
163
```
164

165
### Response Wrapper Classes
166

167
Classes that provide access to raw HTTP responses and additional response metadata.
168

169
```python { .api }
170
class APIResponse:
171
    """
172
    Wrapper for API responses with access to raw HTTP data.
173
    
174
    Provides access to the parsed response object as well as
175
    raw HTTP response data including headers and status codes.
176
    """
177
    def parse(self) -> Any: ...
178
    @property
179
    def headers(self) -> httpx.Headers: ...
180
    @property
181
    def status_code(self) -> int: ...
182
    @property
183
    def request(self) -> httpx.Request: ...
184

185
class AsyncAPIResponse:
186
    """Async version of APIResponse wrapper."""
187
    def parse(self) -> Any: ...
188
    @property
189
    def headers(self) -> httpx.Headers: ...
190
    @property
191
    def status_code(self) -> int: ...
192
    @property
193
    def request(self) -> httpx.Request: ...
194
```
195

196
### HTTP Client Classes
197

198
Default HTTP client configurations optimized for the Cerebras Cloud API.
199

200
```python { .api }
201
class DefaultHttpxClient:
202
    """
203
    Default synchronous httpx client configuration.
204
    
205
    Pre-configured with optimal settings for the Cerebras Cloud API
206
    including connection limits, timeouts, and retry behavior.
207
    """
208

209
class DefaultAsyncHttpxClient:
210
    """
211
    Default asynchronous httpx client configuration.
212
    
213
    Async version of DefaultHttpxClient with the same optimized settings.
214
    """
215

216
class DefaultAioHttpClient:
217
    """
218
    Default aiohttp client configuration.
219
    
220
    Alternative async HTTP client using aiohttp instead of httpx.
221
    """
222
```
223

224
### Configuration Constants
225

226
Default values and limits used throughout the SDK.
227

228
```python { .api }
229
DEFAULT_TIMEOUT: float
230
"""Default request timeout in seconds."""
231

232
DEFAULT_MAX_RETRIES: int
233
"""Default maximum number of retries for failed requests."""
234

235
DEFAULT_CONNECTION_LIMITS: httpx.Limits
236
"""Default HTTP connection pool limits."""
237
```
238

239
### Utility Functions
240

241
Helper functions for file operations and data processing.
242

243
```python { .api }
244
def file_from_path(path: str) -> Any:
245
    """
246
    Load a file from filesystem path for API upload.
247
    
248
    Parameters:
249
    - path: Filesystem path to the file
250
    
251
    Returns:
252
    File object suitable for API upload
253
    """
254
```
255

256
### Package Metadata
257

258
Version and package information constants.
259

260
```python { .api }
261
__version__: str
262
"""Current SDK version string (e.g., "1.50.1")."""
263

264
__title__: str
265
"""Package title/name."""
266
```
267

268
## Usage Examples
269

270
### Exception Handling
271

272
```python
273
from cerebras.cloud.sdk import (
274
    Cerebras, 
275
    APIError, 
276
    AuthenticationError, 
277
    RateLimitError,
278
    APIConnectionError,
279
    APITimeoutError
280
)
281

282
client = Cerebras()
283

284
try:
285
    response = client.chat.completions.create(
286
        model="llama3.1-70b",
287
        messages=[{"role": "user", "content": "Hello!"}]
288
    )
289
except AuthenticationError:
290
    print("Invalid API key - check your CEREBRAS_API_KEY")
291
except RateLimitError as e:
292
    print(f"Rate limit exceeded. Retry after: {e.response.headers.get('retry-after')}")
293
except APIConnectionError:
294
    print("Network connection failed - check internet connectivity")
295
except APITimeoutError:
296
    print("Request timed out - try again or increase timeout")
297
except APIError as e:
298
    print(f"API error: {e.message}")
299
    print(f"Status code: {e.response.status_code if hasattr(e, 'response') else 'N/A'}")
300
```
301

302
### Custom Timeout Configuration
303

304
```python
305
from cerebras.cloud.sdk import Cerebras, Timeout
306
import httpx
307

308
# Simple timeout (30 seconds for all operations)
309
client = Cerebras(timeout=30.0)
310

311
# Detailed timeout configuration
312
custom_timeout = Timeout(
313
    connect=5.0,    # 5 seconds to establish connection
314
    read=30.0,      # 30 seconds to read response
315
    write=10.0,     # 10 seconds to send request
316
    pool=5.0        # 5 seconds to get connection from pool
317
)
318

319
client = Cerebras(timeout=custom_timeout)
320

321
# Using httpx.Timeout directly
322
httpx_timeout = httpx.Timeout(30.0, connect=5.0)
323
client = Cerebras(timeout=httpx_timeout)
324
```
325

326
### Raw Response Access
327

328
```python
329
from cerebras.cloud.sdk import Cerebras
330

331
client = Cerebras()
332

333
# Get raw HTTP response
334
raw_response = client.with_raw_response.chat.completions.create(
335
    model="llama3.1-70b",
336
    messages=[{"role": "user", "content": "Hello!"}]
337
)
338

339
# Access response metadata
340
print(f"Status: {raw_response.status_code}")
341
print(f"Headers: {dict(raw_response.headers)}")
342
print(f"Request ID: {raw_response.headers.get('x-request-id')}")
343

344
# Parse the actual response
345
chat_completion = raw_response.parse()
346
print(f"Response: {chat_completion.choices[0].message.content}")
347
```
348

349
### Using NOT_GIVEN for Optional Parameters
350

351
```python
352
from cerebras.cloud.sdk import Cerebras, NOT_GIVEN
353

354
client = Cerebras()
355

356
# Explicitly unset optional parameters
357
response = client.chat.completions.create(
358
    model="llama3.1-70b",
359
    messages=[{"role": "user", "content": "Hello!"}],
360
    temperature=NOT_GIVEN,  # Use model default
361
    max_tokens=NOT_GIVEN,   # Use model default
362
    top_p=0.9              # Override default
363
)
364
```
365

366
### File Upload Utility
367

368
```python
369
from cerebras.cloud.sdk import file_from_path
370

371
# Load a file for API upload (if supported by specific endpoints)
372
try:
373
    file_obj = file_from_path("/path/to/document.txt")
374
    # Use file_obj in API calls that accept file uploads
375
except FileNotFoundError:
376
    print("File not found")
377
except PermissionError:
378
    print("Permission denied reading file")
379
```
380

381
### Version Information
382

383
```python
384
from cerebras.cloud.sdk import __version__, __title__
385

386
print(f"Using {__title__} version {__version__}")
387

388
# Version-specific feature detection
389
major, minor, patch = __version__.split('.')
390
if int(major) >= 1 and int(minor) >= 50:
391
    print("Advanced features available")
392
```
393

394
### Custom HTTP Client Configuration
395

396
```python
397
import httpx
398
from cerebras.cloud.sdk import Cerebras, DefaultHttpxClient
399

400
# Use the default client with custom settings
401
default_client = DefaultHttpxClient()
402
print(f"Default limits: {default_client.limits}")
403

404
# Create completely custom HTTP client
405
custom_client = httpx.Client(
406
    timeout=httpx.Timeout(60.0),
407
    limits=httpx.Limits(
408
        max_keepalive_connections=10,
409
        max_connections=50,
410
        keepalive_expiry=30.0
411
    ),
412
    headers={"User-Agent": "MyApp/1.0"}
413
)
414

415
client = Cerebras(http_client=custom_client)
416
```
417

418
### Streaming with Error Handling
419

420
```python
421
from cerebras.cloud.sdk import Cerebras, APIError
422

423
client = Cerebras()
424

425
try:
426
    stream = client.chat.completions.create(
427
        model="llama3.1-70b",
428
        messages=[{"role": "user", "content": "Tell me a story"}],
429
        stream=True
430
    )
431
    
432
    for chunk in stream:
433
        if chunk.choices[0].delta.content:
434
            print(chunk.choices[0].delta.content, end="", flush=True)
435
            
436
except APIError as e:
437
    print(f"\nStreaming error: {e.message}")
438
    if hasattr(e, 'response'):
439
        print(f"Status: {e.response.status_code}")
440
```
441

442
### Type Checking with BaseModel
443

444
```python
445
from cerebras.cloud.sdk import Cerebras, BaseModel
446
from cerebras.cloud.sdk.types.chat import ChatCompletion
447

448
client = Cerebras()
449

450
response = client.chat.completions.create(
451
    model="llama3.1-70b",
452
    messages=[{"role": "user", "content": "Hello!"}]
453
)
454

455
# Type checking
456
assert isinstance(response, BaseModel)
457
assert isinstance(response, ChatCompletion)
458

459
# JSON serialization
460
response_json = response.model_dump_json()
461
print(f"Response JSON: {response_json}")
462

463
# Validation
464
try:
465
    # This would raise validation error if data is invalid
466
    ChatCompletion.model_validate({"invalid": "data"})
467
except Exception as e:
468
    print(f"Validation error: {e}")
469
```