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

# Configuration

> Configure tif1 using .tif1rc files, environment variables, or runtime settings

## Overview

The tif1 library provides flexible configuration through three mechanisms:

1. **Configuration file** (`.tif1rc`)
2. **Environment variables** (`TIF1_*`)
3. **Runtime configuration** (programmatic)

Configuration sources are loaded in this priority order (highest to lowest):

1. Environment variables
2. Configuration file (`.tif1rc`)
3. Default values

## Configuration File

Create a `.tif1rc` file in your home directory:

```json theme={null}
{
  "cache_dir": "~/.tif1/cache",
  "enable_cache": true,
  "log_level": "INFO",
  "timeout": 30,
  "max_retries": 3,
  "lib": "pandas"
}
```

### File Locations

The library searches for `.tif1rc` in this order:

1. Path specified in `TIF1_CONFIG_FILE` environment variable
2. Current working directory (only if `TIF1_TRUST_CWD_CONFIG=true`)
3. Home directory (`~/.tif1rc`)

```bash theme={null}
# Use custom config file location
export TIF1_CONFIG_FILE="/path/to/custom/.tif1rc"

# Trust config file in current directory (security consideration)
export TIF1_TRUST_CWD_CONFIG=true
```

## Environment Variables

All configuration options can be set via environment variables:

```bash theme={null}
# Cache settings
export TIF1_CACHE_DIR="/custom/cache/path"
export TIF1_ENABLE_CACHE=true

# Network settings
export TIF1_TIMEOUT=30
export TIF1_MAX_RETRIES=3
export TIF1_MAX_CONCURRENT_REQUESTS=20

# Backend selection
export TIF1_LIB=polars

# Logging
export TIF1_LOG_LEVEL=INFO
```

## Runtime Configuration

Modify configuration programmatically:

```python theme={null}
from tif1.config import get_config

config = get_config()

# Set values
config.set("cache_dir", "/custom/path")
config.set("lib", "polars")
config.set("timeout", 60)

# Get values
cache_dir = config.get("cache_dir")
print(f"Cache directory: {cache_dir}")

# Save configuration to file
from pathlib import Path
config.save(Path("~/.tif1rc"))
```

## Configuration Options

### Cache Settings

| Option                             | Type    | Default         | Description                            |
| ---------------------------------- | ------- | --------------- | -------------------------------------- |
| `cache_dir`                        | string  | `~/.cache/tif1` | Cache directory path                   |
| `enable_cache`                     | boolean | `true`          | Enable/disable caching                 |
| `cache_commit_interval`            | integer | `25`            | SQLite commit frequency                |
| `sqlite_timeout`                   | float   | `30.0`          | SQLite lock timeout (seconds)          |
| `memory_cache_max_items`           | integer | `1024`          | Max memory cache items (laps/sessions) |
| `memory_telemetry_cache_max_items` | integer | `2048`          | Max memory cache items (telemetry)     |

```json theme={null}
{
  "cache_dir": "~/.tif1/cache",
  "enable_cache": true,
  "cache_commit_interval": 25,
  "sqlite_timeout": 30.0,
  "memory_cache_max_items": 1024,
  "memory_telemetry_cache_max_items": 2048
}
```

### Network Settings

| Option                    | Type    | Default | Description                    |
| ------------------------- | ------- | ------- | ------------------------------ |
| `timeout`                 | integer | `30`    | HTTP request timeout (seconds) |
| `max_retries`             | integer | `3`     | Maximum retry attempts         |
| `retry_backoff_factor`    | float   | `2.0`   | Exponential backoff factor     |
| `retry_jitter`            | boolean | `true`  | Add jitter to retries          |
| `max_retry_delay`         | float   | `60.0`  | Maximum retry delay (seconds)  |
| `max_concurrent_requests` | integer | `20`    | Max parallel requests          |
| `http2_max_connections`   | integer | `10`    | Max HTTP/2 connections         |
| `http2_max_pool_size`     | integer | `20`    | HTTP/2 connection pool size    |
| `http_multiplexed`        | boolean | `true`  | Enable HTTP/2 multiplexing     |
| `http_disable_http3`      | boolean | `false` | Disable HTTP/3                 |

```json theme={null}
{
  "timeout": 30,
  "max_retries": 3,
  "retry_backoff_factor": 2.0,
  "max_concurrent_requests": 20
}
```

### Circuit Breaker Settings

| Option                      | Type    | Default | Description                     |
| --------------------------- | ------- | ------- | ------------------------------- |
| `circuit_breaker_threshold` | integer | `5`     | Failures before opening circuit |
| `circuit_breaker_timeout`   | integer | `60`    | Circuit reset timeout (seconds) |

```json theme={null}
{
  "circuit_breaker_threshold": 5,
  "circuit_breaker_timeout": 60
}
```

### Backend Settings

| Option                   | Type    | Default    | Description                            |
| ------------------------ | ------- | ---------- | -------------------------------------- |
| `lib`                    | string  | `"pandas"` | Backend library (`pandas` or `polars`) |
| `polars_lap_categorical` | boolean | `false`    | Use categorical types in Polars        |

```json theme={null}
{
  "lib": "polars",
  "polars_lap_categorical": false
}
```

### Logging Settings

| Option      | Type   | Default     | Description                             |
| ----------- | ------ | ----------- | --------------------------------------- |
| `log_level` | string | `"WARNING"` | Log level (DEBUG, INFO, WARNING, ERROR) |

```json theme={null}
{
  "log_level": "INFO"
}
```

### Validation Settings

| Option               | Type    | Default | Description                 |
| -------------------- | ------- | ------- | --------------------------- |
| `validate_data`      | boolean | `false` | Enable data validation      |
| `validate_lap_times` | boolean | `false` | Enable lap time validation  |
| `validate_telemetry` | boolean | `false` | Enable telemetry validation |

```json theme={null}
{
  "validate_data": true,
  "validate_lap_times": true,
  "validate_telemetry": true
}
```

### Performance Settings

| Option                                       | Type    | Default | Description                                |
| -------------------------------------------- | ------- | ------- | ------------------------------------------ |
| `max_workers`                                | integer | `20`    | Thread pool size                           |
| `json_parse_workers`                         | integer | `0`     | Process pool for JSON parsing (0=disabled) |
| `ultra_cold_start`                           | boolean | `true`  | Optimize for cold cache startup            |
| `prefetch_driver_laps_on_get_driver`         | boolean | `true`  | Prefetch driver laps                       |
| `telemetry_prefetch_max_concurrent_requests` | integer | `32`    | Max concurrent telemetry requests          |

```json theme={null}
{
  "max_workers": 20,
  "ultra_cold_start": true,
  "prefetch_driver_laps_on_get_driver": true
}
```

### CDN Settings

| Option                 | Type    | Default                                           | Description       |
| ---------------------- | ------- | ------------------------------------------------- | ----------------- |
| `cdns`                 | array   | `["https://cdn.jsdelivr.net/gh/TracingInsights"]` | CDN base URLs     |
| `cdn_use_minification` | boolean | `false`                                           | Use minified JSON |

```json theme={null}
{
  "cdns": [
    "https://cdn.jsdelivr.net/gh/TracingInsights"
  ],
  "cdn_use_minification": false
}
```

### Special Modes

| Option         | Type    | Default | Description                |
| -------------- | ------- | ------- | -------------------------- |
| `offline_mode` | boolean | `false` | Use cache only, no network |
| `ci_mode`      | boolean | `false` | CI/CD optimizations        |

```json theme={null}
{
  "offline_mode": false,
  "ci_mode": false
}
```

## Complete Configuration Example

Here's a complete `.tif1rc` file with common settings:

```json theme={null}
{
  "cache_dir": "~/.tif1/cache",
  "enable_cache": true,
  "log_level": "INFO",
  "timeout": 30,
  "max_retries": 3,
  "retry_backoff_factor": 2.0,
  "max_concurrent_requests": 20,
  "lib": "pandas",
  "circuit_breaker_threshold": 5,
  "circuit_breaker_timeout": 60,
  "validate_data": false,
  "ultra_cold_start": true,
  "prefetch_driver_laps_on_get_driver": true
}
```

## Environment Variables Example

```bash theme={null}
#!/bin/bash

# Cache configuration
export TIF1_CACHE_DIR="~/.tif1/cache"
export TIF1_ENABLE_CACHE=true

# Network configuration
export TIF1_TIMEOUT=30
export TIF1_MAX_RETRIES=3
export TIF1_MAX_CONCURRENT_REQUESTS=20

# Backend configuration
export TIF1_LIB=polars

# Logging
export TIF1_LOG_LEVEL=INFO

# Performance
export TIF1_ULTRA_COLD_START=true
export TIF1_PREFETCH_DRIVER_LAPS_ON_GET_DRIVER=true

# Run your script
python your_analysis.py
```

## Runtime Configuration Example

```python theme={null}
import tif1
from tif1.config import get_config

# Get configuration instance
config = get_config()

# View current settings
print(f"Cache dir: {config.get('cache_dir')}")
print(f"Backend: {config.get('lib')}")
print(f"Timeout: {config.get('timeout')}")

# Modify settings
config.set("lib", "polars")
config.set("max_concurrent_requests", 32)
config.set("log_level", "DEBUG")

# Enable validation for debugging
config.set("validate_data", True)
config.set("validate_lap_times", True)

# Use custom cache directory
config.set("cache_dir", "/mnt/fast-ssd/tif1-cache")

# Save to file for future use
from pathlib import Path
config.save(Path("~/.tif1rc").expanduser())
print("Configuration saved!")

# Now use tif1 with new settings
session = tif1.get_session(2025, "Monaco Grand Prix", "Race")
```

## Configuration Best Practices

### Development

```json theme={null}
{
  "log_level": "DEBUG",
  "validate_data": true,
  "validate_lap_times": true,
  "validate_telemetry": true,
  "enable_cache": true
}
```

### Production

```json theme={null}
{
  "log_level": "WARNING",
  "validate_data": false,
  "enable_cache": true,
  "max_concurrent_requests": 32,
  "ultra_cold_start": true
}
```

### CI/CD

```json theme={null}
{
  "ci_mode": true,
  "enable_cache": false,
  "timeout": 60,
  "max_retries": 5,
  "log_level": "INFO"
}
```

### Offline Analysis

```json theme={null}
{
  "offline_mode": true,
  "enable_cache": true,
  "log_level": "INFO"
}
```

## Next Steps

* Learn about [caching](/guides/caching) to optimize performance
* Explore [backends](/guides/backends) for choosing pandas vs polars
* Understand [error handling](/guides/error-handling) for configuration errors