# How Twinkle Eval Handles SSL Verification and API Timeout Configuration

> Learn how Twinkle Eval manages SSL verification and API timeout settings. Explore secure defaults and streamlined configuration within config.yaml for enhanced API interactions.

- Repository: [Twinkle AI/eval](https://github.com/ai-twinkle/eval)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Twinkle Eval centralizes SSL verification and API timeout controls in [`config.yaml`](https://github.com/ai-twinkle/eval/blob/main/config.yaml), applying secure defaults of 600 seconds for timeouts and enabled SSL verification before passing these values directly to the underlying HTTP client.**

The `ai-twinkle/eval` repository provides a flexible evaluation framework for Large Language Models (LLMs) that requires robust network configuration handling. Understanding how Twinkle Eval manages **SSL verification** and **API timeout configuration** is essential for deploying the tool in both development and production environments with varying security and performance requirements.

## Configuration Defaults in ConfigurationManager

When the configuration loads, the `ConfigurationManager._apply_defaults` method in [`twinkle_eval/config.py`](https://github.com/ai-twinkle/eval/blob/main/twinkle_eval/config.py) injects sensible defaults for network security parameters. This ensures the system operates securely even when users omit specific settings in their configuration files.

### SSL Verification Settings

By default, Twinkle Eval enables strict SSL certificate verification to maintain secure connections. The `disable_ssl_verify` parameter defaults to `False` in [`twinkle_eval/config.py`](https://github.com/ai-twinkle/eval/blob/main/twinkle_eval/config.py) lines 75‑80, meaning SSL verification remains active unless explicitly disabled. This default protects against man-in-the-middle attacks while allowing flexibility for testing environments with self-signed certificates.

### API Timeout Configuration

The framework sets a generous default timeout of **600 seconds** (10 minutes) for API requests. This value, also established in [`twinkle_eval/config.py`](https://github.com/ai-twinkle/eval/blob/main/twinkle_eval/config.py) lines 75‑80, prevents indefinite hanging while accommodating slow LLM responses. Users can override this based on their specific latency requirements and network conditions.

## Passing Settings to the LLM Client

The `OpenAIModel` class in [`twinkle_eval/models.py`](https://github.com/ai-twinkle/eval/blob/main/twinkle_eval/models.py) translates configuration values into concrete HTTP client behavior. Lines 48‑59 demonstrate how the system constructs both an `httpx.Client` and an `OpenAI` client using the validated configuration parameters.

When `disable_ssl_verify` is set to `True`, the code instantiates the HTTP client with `verify=False`, bypassing certificate validation. Conversely, the default `False` value maintains standard SSL verification. The timeout value passes directly to the `OpenAI` client constructor via its `timeout` argument, ensuring consistent request duration limits across all API calls.

## Validating Configuration Parameters

Before reaching the client construction stage, [`twinkle_eval/validators.py`](https://github.com/ai-twinkle/eval/blob/main/twinkle_eval/validators.py) enforces type safety and logical constraints on both parameters. The validation logic at lines 85‑87 confirms that `timeout` is a positive number, while separate checks verify that `disable_ssl_verify` is strictly a boolean value. This early validation prevents runtime errors and ensures malformed configurations fail fast during initialization.

## Practical Configuration Examples

Configure these settings through the central [`config.yaml`](https://github.com/ai-twinkle/eval/blob/main/config.yaml) file to control network behavior without modifying source code.

```yaml

# config.yaml – custom SSL & timeout settings

llm_api:
  type: openai
  api_key: YOUR_API_KEY
  base_url: https://api.openai.com/v1
  disable_ssl_verify: true      # skip SSL certificate verification

  timeout: 120                  # 2‑minute request timeout

  max_retries: 2

```

Once configured, the framework automatically applies these settings when loading the LLM instance:

```python

# Using the configured LLM (no extra code needed)

from twinkle_eval.config import load_config

cfg = load_config()                     # reads the YAML above

llm = cfg["llm_instance"]              # OpenAIModel created by the factory

response = llm.call("Explain quantum entanglement?")
print(response.choices[0].message.content)

```

Changing `disable_ssl_verify` to `false` re‑enables normal certificate checks, while adjusting `timeout` controls how long the client will wait for a response before raising an error.

## Summary

- **Centralized configuration**: Both SSL verification and timeout settings reside in [`config.yaml`](https://github.com/ai-twinkle/eval/blob/main/config.yaml), managed by `ConfigurationManager._apply_defaults` in [`twinkle_eval/config.py`](https://github.com/ai-twinkle/eval/blob/main/twinkle_eval/config.py).
- **Secure defaults**: SSL verification defaults to enabled (`False` for `disable_ssl_verify`) and timeouts default to 600 seconds.
- **Client integration**: `OpenAIModel` in [`twinkle_eval/models.py`](https://github.com/ai-twinkle/eval/blob/main/twinkle_eval/models.py) passes these values directly to `httpx.Client` and the `OpenAI` client constructor.
- **Validation layer**: [`twinkle_eval/validators.py`](https://github.com/ai-twinkle/eval/blob/main/twinkle_eval/validators.py) enforces boolean types for SSL settings and positive numeric values for timeouts at lines 85‑87.
- **Flexible deployment**: Users can disable SSL verification for testing or adjust timeouts for specific network conditions without code changes.

## Frequently Asked Questions

### How do I disable SSL certificate verification in Twinkle Eval?

Set `disable_ssl_verify: true` in your [`config.yaml`](https://github.com/ai-twinkle/eval/blob/main/config.yaml) under the `llm_api` section. According to the source code in [`twinkle_eval/models.py`](https://github.com/ai-twinkle/eval/blob/main/twinkle_eval/models.py), this passes `verify=False` to the underlying `httpx.Client`, bypassing certificate validation for environments with self-signed certificates.

### What is the default API timeout and how can I change it?

The default timeout is **600 seconds** (10 minutes) as defined in [`twinkle_eval/config.py`](https://github.com/ai-twinkle/eval/blob/main/twinkle_eval/config.py). Override this by specifying a `timeout` value in seconds within your [`config.yaml`](https://github.com/ai-twinkle/eval/blob/main/config.yaml) file. The `OpenAIModel` class passes this value directly to the OpenAI client constructor.

### Why does Twinkle Eval validate configuration parameters before use?

The [`validators.py`](https://github.com/ai-twinkle/eval/blob/main/validators.py) module checks that `timeout` is a positive number and `disable_ssl_verify` is a boolean to prevent runtime errors. This validation occurs at initialization, ensuring that malformed configurations fail immediately rather than causing cryptic HTTP errors during LLM calls.

### Can I configure different timeout values for different LLM providers?

The current implementation in `ai-twinkle/eval` uses a unified timeout setting passed through the central configuration. While the base [`config.yaml`](https://github.com/ai-twinkle/eval/blob/main/config.yaml) structure supports provider-specific settings, the `OpenAIModel` implementation in [`twinkle_eval/models.py`](https://github.com/ai-twinkle/eval/blob/main/twinkle_eval/models.py) applies a single timeout value to all HTTP clients created from that configuration.