MCP-Template / rules

---
description: How to use global config across the project.
globs:
alwaysApply: true
---
## Using global configuration

Global config is used to store hyperparameters that should be applied across the entire codebase. The configuration system uses **pydantic-settings** for automatic validation and type checking. They handle both environment variables (should not be committed to the repo) and other configuration values (safe to commit to the repo).

**Configuration Files:**
- `common/global_config.yaml` - Base configuration values
- `common/<name>.yaml` - Optional split config files (contents loaded under root key `<name>`)
- `common/config_models.py` - Pydantic models defining structure and validation
- `common/global_config.py` - Main Config class using BaseSettings
- `.env` - Environment variables and secrets (git-ignored)

You can split config sections into their own YAML files in `common/`. For example, `common/logging.yaml` will have its contents loaded under the `logging` root key, equivalent to defining that section inline in `global_config.yaml`. If `global_config.yaml` already defines the same root key, a `KeyError` is raised to prevent conflicts.

Whenever there is a hyperparameter that should be applied across the entire codebase, add those hyperparameters in `common/global_config.yaml` (or a split file). Whenever a user seems to have defined a hyperparameter in the wrong scope, or using a constant value in their code point them towards `common/global_config.yaml` and ask them to add it there instead.

Examples of this are:
- `MAX_RETRIES`
- `MODEL_NAME`
- etc, etc

Any private or secret keys should be stored in the .env file in the root of the project, which is automatically loaded into common.

Examples of this are:
- `OPENAI_API_KEY`
- `GITHUB_PERSONAL_ACCESS_TOKEN`
- etc, etc

To add new configuration fields with nested structures, define the corresponding Pydantic model in `common/config_models.py` first, then add the field to the `Config` class in `common/global_config.py`.

Then, these common values can be accessed in python files using:

```yaml file=common/global_config.yaml
example_key: example_value
example_parent:
  example_child: example_value
```

```python
from common import global_config

# Handling non-secrets
print(global_config.example_parent.example_child)

# Handling secrets
print(global_config.OPENAI_API_KEY)
```