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

# Settings

> Global configuration, defaults, and provider identifiers in RAGLight.

The `Settings` class is the **central configuration backbone** of RAGLight. It provides a single source of truth for:

* **Provider Identifiers** (LLMs, embeddings, vector stores)
* **Default Models** (optimized for local use)
* **Environment Configuration** (loading `.env` automatically)

<Info>
  **Philosophy**: RAGLight avoids "magic values". All defaults are exposed as
  constants in `Settings`, making pipelines predictable, debuggable, and easy to
  override.
</Info>

## Global Setup

### Logging

Before building any pipeline, it is recommended to initialize the logging system. This ensures that RAGLight's internal logs (ingestion progress, retrieval stats) are formatted correctly.

```python theme={null}
from raglight.config.settings import Settings

# Call this once at the start of your script to enable structured logging
Settings.setup_logging()
```

***

## Provider Identifiers

RAGLight uses string constants to identify providers. Using these constants prevents typo-related errors when configuring your `RAGConfig`.

### LLM & Embeddings

These constants are used in `RAGConfig.provider` and `VectorStoreConfig.provider`.

| Constant                 | Value             | Description                                                    |
| :----------------------- | :---------------- | :------------------------------------------------------------- |
| `Settings.OLLAMA`        | `"ollama"`        | **Recommended for local.** Requires an Ollama instance.        |
| `Settings.OPENAI`        | `"openai"`        | Uses OpenAI API (requires key).                                |
| `Settings.MISTRAL`       | `"mistral"`       | Uses Mistral API (requires key).                               |
| `Settings.VLLM`          | `"vllm"`          | Connects to a vLLM server (high throughput).                   |
| `Settings.LMSTUDIO`      | `"lmstudio"`      | Connects to LM Studio local server.                            |
| `Settings.GOOGLE_GEMINI` | `"google_gemini"` | Uses Google's Gemini API.                                      |
| `Settings.HUGGINGFACE`   | `"huggingface"`   | **Embeddings only.** Runs locally via `sentence-transformers`. |

### Vector Stores

| Constant          | Value      | Description                                     |
| :---------------- | :--------- | :---------------------------------------------- |
| `Settings.CHROMA` | `"chroma"` | **Default.** Local, persistent vector database. |

***

## Default Configuration

RAGLight ships with "batteries-included" defaults, optimized for a standard local laptop (Apple Silicon / NVIDIA GPU).

<CodeGroup>
  ```python LLM Defaults theme={null}
  # Default Model (usually "llama3")
  Settings.DEFAULT_LLM

  # Reasoning / Agentic Model

  Settings.DEFAULT_REASONING_LLM

  ```

  ```python Embedding Defaults theme={null}
  # Fast, local embeddings (all-MiniLM-L6-v2)
  Settings.DEFAULT_EMBEDDINGS_MODEL

  # Cross-Encoder for Reranking (optional)
  Settings.DEFAULT_CROSS_ENCODER_MODEL
  ```

  ```python Retrieval Defaults theme={null}
  # Number of chunks to retrieve per query
  Settings.DEFAULT_K = 5

  # Default Vector Store Collection Name
  Settings.DEFAULT_COLLECTION_NAME

  # Default Persist Directory
  Settings.DEFAULT_PERSIST_DIRECTORY
  ```
</CodeGroup>

### System Prompts

You can inspect or override the default system prompts used by the pipelines. These are designed to be readable and inspectable.

```python theme={null}
# Standard RAG prompt
print(Settings.DEFAULT_SYSTEM_PROMPT)

# Agentic RAG prompt (Tool use & reasoning rules)
print(Settings.DEFAULT_AGENT_PROMPT)
```

***

## Environment Variables

`Settings` automatically looks for a `.env` file in your working directory using `python-dotenv`. This is the secure way to manage API keys and custom endpoints without hardcoding them.

<CardGroup cols={2}>
  <Card title="API Keys" icon="key">
    Supported keys for remote providers: \* `OPENAI_API_KEY` \* `MISTRAL_API_KEY`

    * `GEMINI_API_KEY` \* `ANTHROPIC_API_KEY`
  </Card>

  <Card title="Custom Endpoints" icon="server">
    URLs for local/custom servers: \* `OLLAMA_CLIENT_URL` (default:
    `http://localhost:11434`) \* `LMSTUDIO_CLIENT` \* `OPENAI_CLIENT_URL` (useful
    for vLLM/compatible APIs)
  </Card>
</CardGroup>

### Example `.env` File

Create a `.env` file in your project root:

```bash .env theme={null}
# Use a custom Ollama instance on another machine
OLLAMA_CLIENT_URL=http://192.168.1.50:11434

# OpenAI Fallback
OPENAI_API_KEY=sk-proj-12345...
```

### REST API variables (`raglight serve`)

When running `raglight serve`, the server reads an additional set of `RAGLIGHT_*` variables to configure the pipeline without any Python code.

| Variable                       | Default                  | Description                             |
| :----------------------------- | :----------------------- | :-------------------------------------- |
| `RAGLIGHT_LLM_MODEL`           | `llama3`                 | LLM model name                          |
| `RAGLIGHT_LLM_PROVIDER`        | `Ollama`                 | LLM provider                            |
| `RAGLIGHT_LLM_API_BASE`        | `http://localhost:11434` | LLM API base URL                        |
| `RAGLIGHT_EMBEDDINGS_MODEL`    | `all-MiniLM-L6-v2`       | Embeddings model name                   |
| `RAGLIGHT_EMBEDDINGS_PROVIDER` | `HuggingFace`            | Embeddings provider                     |
| `RAGLIGHT_EMBEDDINGS_API_BASE` | `http://localhost:11434` | Embeddings API base URL                 |
| `RAGLIGHT_PERSIST_DIR`         | `./raglight_db`          | ChromaDB persistence directory          |
| `RAGLIGHT_COLLECTION`          | `default`                | ChromaDB collection name                |
| `RAGLIGHT_K`                   | `5`                      | Number of retrieved documents per query |
| `RAGLIGHT_SYSTEM_PROMPT`       | *(default prompt)*       | Custom system prompt                    |
| `RAGLIGHT_CHROMA_HOST`         | —                        | Remote Chroma host                      |
| `RAGLIGHT_CHROMA_PORT`         | —                        | Remote Chroma port                      |

See the [REST API](/documentation/rest-api) page for the full deployment guide.

***

## Ignore Folders

When using `FolderSource` to ingest data, RAGLight automatically ignores common build, cache, and system directories to keep your index clean and relevant.

```python theme={null}
# Returns a list of ignored directories
ignored_list = Settings.DEFAULT_IGNORE_FOLDERS
```

**Includes by default:**

* `.git`, `.vscode`, `.idea`
* `__pycache__`, `venv`, `env`
* `node_modules`
* `dist`, `build`
* `.DS_Store`