> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useocular.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure the Ocular SDK for your environment

# SDK Configuration

**After installing the Ocular SDK, you'll need to configure it with your API credentials.** This guide covers all available configuration options.

## Basic Configuration

<Check>
  All you need to get started is your API key. Everything else has sensible defaults.
</Check>

### Direct Initialization

<Note>
  This is the simplest way to get started with the SDK for testing and development.
</Note>

You can also configure the SDK directly in your code:

```python theme={null}
from ocular import Ocular

# Initialize with direct configuration
ocular = Ocular(api_key="your_api_key_here")
```

<Warning>
  Avoid hardcoding API keys in production code. Use environment variables instead.
</Warning>

## Configuration Parameters

<Info>
  Understanding these parameters will help you optimize the SDK for your specific use case.
</Info>

The SDK accepts the following parameters during initialization:

| Parameter           | Type    | Default                                                  | Description                            |
| ------------------- | ------- | -------------------------------------------------------- | -------------------------------------- |
| **api\_key**        | string  | None                                                     | **Your Ocular API key (required)**     |
| **api\_url**        | string  | "[https://api.useocular.com](https://api.useocular.com)" | Base URL for the Ocular API            |
| **timeout**         | integer | 300                                                      | Request timeout in seconds             |
| **max\_retries**    | integer | 3                                                        | Maximum number of retry attempts       |
| **backoff\_factor** | float   | 0.5                                                      | Exponential backoff factor for retries |
| **debug**           | boolean | False                                                    | Enable detailed logging                |

<Info>
  Most users will only need to set the API key. The default values work well for standard use cases.
</Info>

## Complete Example

<Tip>
  Copy this example to quickly get started with a fully configured SDK instance.
</Tip>

```python theme={null}
from ocular import Ocular

# Initialize with all available options
ocular = Ocular(
    api_key="your_api_key_here",
    api_url="https://api.useocular.com",
    timeout=300,
    max_retries=3,
    backoff_factor=0.5,
    debug=False
)

# Access your workspace
workspace = ocular.workspace("your_workspace_id")
```

## Environment Variables

<Check>
  Using environment variables is the recommended approach for production deployments.
</Check>

All configuration can be set using environment variables:

| Variable                    | Description          | Default                                                  |
| --------------------------- | -------------------- | -------------------------------------------------------- |
| **OCULAR\_API\_KEY**        | Your API key         | Required                                                 |
| **OCULAR\_API\_URL**        | API base URL         | "[https://api.useocular.com](https://api.useocular.com)" |
| **OCULAR\_TIMEOUT**         | Request timeout      | 300                                                      |
| **OCULAR\_MAX\_RETRIES**    | Max retry attempts   | 3                                                        |
| **OCULAR\_BACKOFF\_FACTOR** | Retry backoff factor | 0.5                                                      |
| **OCULAR\_DEBUG**           | Debug mode           | false                                                    |

<Tip>
  Using environment variables is recommended for production environments to keep sensitive information out of your code.
</Tip>

## Using With Python dotenv

<Note>
  This approach combines the security of environment variables with the convenience of a configuration file.
</Note>

For development, you can use a `.env` file with the python-dotenv package:

```
# .env file
OCULAR_API_KEY=your_api_key_here
```

Then in your code:

```python theme={null}
from dotenv import load_dotenv
import os
from ocular import Ocular

# Load environment variables from .env file
load_dotenv()

# Initialize using values from .env
ocular = Ocular(api_key=os.environ.get("OCULAR_API_KEY"))
```

<Warning>
  Never commit your .env file to version control. Add it to your .gitignore file.
</Warning>