Types and Configuration

class BaseModel:
    """
    Base Pydantic model class for all API response objects.
    
    Provides JSON serialization, validation, and type coercion for all
    response models in the SDK.
    """

class NoneType:
    """Type annotation helper for None values."""

class NotGiven:
    """
    Sentinel type for optional parameters that have not been provided.
    
    Used to distinguish between None (explicit null value) and 
    unset parameters in API calls.
    """

NOT_GIVEN: NotGiven
"""Sentinel instance for unset parameters."""

class Omit:
    """
    Type utility for omitting fields from TypedDicts.
    
    Used in type annotations to indicate fields that should be
    excluded from certain operations.
    """

# Timeout configuration
Timeout: TypeAlias = Union[float, httpx.Timeout, None]
"""Type alias for timeout values - can be float (seconds), httpx.Timeout object, or None."""

# Transport configuration  
Transport: TypeAlias = httpx.HTTPTransport
"""Type alias for HTTP transport configuration."""

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

# Request options
RequestOptions: TypeAlias = Dict[str, Any]
"""Type alias for per-request configuration options."""

class CerebrasError(Exception):
    """Base exception class for all SDK errors."""

class APIError(CerebrasError):
    """
    Base class for API-related errors.
    
    Attributes:
    - message: Error message describing the issue
    - request: The httpx.Request that caused the error
    - body: The API response body (if available)
    """
    message: str
    request: httpx.Request
    body: object | None

class APIStatusError(APIError):
    """
    Base class for HTTP status code errors.
    
    Raised when the API returns a non-2xx status code.
    """
    status_code: int
    response: httpx.Response

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

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

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

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

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

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

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

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

class APIConnectionError(APIError):
    """
    Network connection error.
    
    Raised when unable to connect to the API due to network issues.
    """

class APITimeoutError(APIError):
    """
    Request timeout error.
    
    Raised when a request times out before receiving a response.
    """

class APIResponseValidationError(APIError):
    """
    Response validation error.
    
    Raised when the API response does not match the expected schema.
    """

class Stream:
    """
    Synchronous streaming response handler.
    
    Provides iteration interface for processing streaming API responses
    in real-time as data arrives from the server.
    """
    def __iter__(self) -> Iterator[Any]: ...
    def __next__(self) -> Any: ...

class AsyncStream:
    """
    Asynchronous streaming response handler.
    
    Async version of Stream for use with async/await patterns.
    """
    def __aiter__(self) -> AsyncIterator[Any]: ...
    async def __anext__(self) -> Any: ...

class APIResponse:
    """
    Wrapper for API responses with access to raw HTTP data.
    
    Provides access to the parsed response object as well as
    raw HTTP response data including headers and status codes.
    """
    def parse(self) -> Any: ...
    @property
    def headers(self) -> httpx.Headers: ...
    @property
    def status_code(self) -> int: ...
    @property
    def request(self) -> httpx.Request: ...

class AsyncAPIResponse:
    """Async version of APIResponse wrapper."""
    def parse(self) -> Any: ...
    @property
    def headers(self) -> httpx.Headers: ...
    @property
    def status_code(self) -> int: ...
    @property
    def request(self) -> httpx.Request: ...

class DefaultHttpxClient:
    """
    Default synchronous httpx client configuration.
    
    Pre-configured with optimal settings for the Cerebras Cloud API
    including connection limits, timeouts, and retry behavior.
    """

class DefaultAsyncHttpxClient:
    """
    Default asynchronous httpx client configuration.
    
    Async version of DefaultHttpxClient with the same optimized settings.
    """

class DefaultAioHttpClient:
    """
    Default aiohttp client configuration.
    
    Alternative async HTTP client using aiohttp instead of httpx.
    """

DEFAULT_TIMEOUT: float
"""Default request timeout in seconds."""

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

DEFAULT_CONNECTION_LIMITS: httpx.Limits
"""Default HTTP connection pool limits."""

def file_from_path(path: str) -> Any:
    """
    Load a file from filesystem path for API upload.
    
    Parameters:
    - path: Filesystem path to the file
    
    Returns:
    File object suitable for API upload
    """

__version__: str
"""Current SDK version string (e.g., "1.50.1")."""

__title__: str
"""Package title/name."""

from cerebras.cloud.sdk import (
    Cerebras, 
    APIError, 
    AuthenticationError, 
    RateLimitError,
    APIConnectionError,
    APITimeoutError
)

client = Cerebras()

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

from cerebras.cloud.sdk import Cerebras, Timeout
import httpx

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

# Detailed timeout configuration
custom_timeout = Timeout(
    connect=5.0,    # 5 seconds to establish connection
    read=30.0,      # 30 seconds to read response
    write=10.0,     # 10 seconds to send request
    pool=5.0        # 5 seconds to get connection from pool
)

client = Cerebras(timeout=custom_timeout)

# Using httpx.Timeout directly
httpx_timeout = httpx.Timeout(30.0, connect=5.0)
client = Cerebras(timeout=httpx_timeout)

from cerebras.cloud.sdk import Cerebras

client = Cerebras()

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

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

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

from cerebras.cloud.sdk import Cerebras, NOT_GIVEN

client = Cerebras()

# Explicitly unset optional parameters
response = client.chat.completions.create(
    model="llama3.1-70b",
    messages=[{"role": "user", "content": "Hello!"}],
    temperature=NOT_GIVEN,  # Use model default
    max_tokens=NOT_GIVEN,   # Use model default
    top_p=0.9              # Override default
)

from cerebras.cloud.sdk import file_from_path

# Load a file for API upload (if supported by specific endpoints)
try:
    file_obj = file_from_path("/path/to/document.txt")
    # Use file_obj in API calls that accept file uploads
except FileNotFoundError:
    print("File not found")
except PermissionError:
    print("Permission denied reading file")

from cerebras.cloud.sdk import __version__, __title__

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

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

import httpx
from cerebras.cloud.sdk import Cerebras, DefaultHttpxClient

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

# Create completely custom HTTP client
custom_client = httpx.Client(
    timeout=httpx.Timeout(60.0),
    limits=httpx.Limits(
        max_keepalive_connections=10,
        max_connections=50,
        keepalive_expiry=30.0
    ),
    headers={"User-Agent": "MyApp/1.0"}
)

client = Cerebras(http_client=custom_client)

from cerebras.cloud.sdk import Cerebras, APIError

client = Cerebras()

try:
    stream = client.chat.completions.create(
        model="llama3.1-70b",
        messages=[{"role": "user", "content": "Tell me a story"}],
        stream=True
    )
    
    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)
            
except APIError as e:
    print(f"\nStreaming error: {e.message}")
    if hasattr(e, 'response'):
        print(f"Status: {e.response.status_code}")

from cerebras.cloud.sdk import Cerebras, BaseModel
from cerebras.cloud.sdk.types.chat import ChatCompletion

client = Cerebras()

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

# Type checking
assert isinstance(response, BaseModel)
assert isinstance(response, ChatCompletion)

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

# Validation
try:
    # This would raise validation error if data is invalid
    ChatCompletion.model_validate({"invalid": "data"})
except Exception as e:
    print(f"Validation error: {e}")