steward_mirror/MIGRATION_NOTES.md

# Test Settings Migration Notes

## Overview
Updated all test files to work with the new OmegaConf-based configuration system while maintaining backward compatibility through a helper function.

## What Changed

### 1. Created `tests/conftest.py` (new file)
- Implements `make_settings(**kwargs)` helper function
- Maps legacy parameter names to the new nested structure
- Used as a shared utility across all test files

### 2. Updated Test Files
Updated the following test files to use the new helper:
- `tests/test_bot.py`
- `tests/test_llm_client.py`
- `tests/test_proposals.py`
- `tests/test_thread_memory.py`
- `tests/test_tools.py`

Each file now:
1. Imports `make_settings` from `tests.conftest`
2. Keeps local `_make_settings()` wrapper for compatibility
3. Calls the shared `make_settings()` function internally

## Parameter Mapping

The `make_settings()` function handles the following legacy-to-new mappings:

### Telegram Config
- `telegram_bot_token` → `telegram.bot_token`
- `telegram_allowed_user_ids` → `telegram.allowed_user_ids`
- `telegram_group_ids` → `telegram.group_ids`

### OpenAI Config
- `openai_api_key` → `openai.api_key`
- `openai_base_url` → `openai.base_url` (default: `"https://api.openai.com/v1"`)
- `openai_model` → `openai.model` (default: `"gpt-4o"`)
- `openai_system_prompt` → `openai.system_prompt` (uses default if not provided)

### Analysis Config
- `analysis_target_url` → `analysis.target_url`
- `analysis_target_api_key` → `analysis.target_api_key`
- `analysis_cron_hour` → `analysis.cron_hour` (default: `8`)
- `analysis_cron_minute` → `analysis.cron_minute` (default: `0`)

### Memory Config
- `thread_memory_path` → `memory.thread_memory_path` (default: `"thread_memory.json"`)

### Tools Config
- `mcp_server_url` → `tools.mcp_server_url`
- `mcp_server_api_key` → `tools.mcp_server_api_key`

## Usage Examples

### Before (would fail with new Settings class)
```python
settings = Settings(
    telegram_bot_token="token",
    openai_api_key="key",
    telegram_allowed_user_ids=[1, 2, 3]
)
```

### After (with new helper)
```python
from tests.conftest import make_settings

settings = make_settings(
    telegram_bot_token="token",
    openai_api_key="key",
    telegram_allowed_user_ids=[1, 2, 3]
)

# Now settings.telegram.bot_token == "token"
# And settings.telegram.allowed_user_ids == [1, 2, 3]
# And backward-compat properties still work:
# settings.telegram_bot_token == "token"
# settings.telegram_allowed_user_ids == [1, 2, 3]
```

## How Test Files Use It

Each test file has a local `_make_settings()` wrapper that:
1. Defines default values specific to that test module
2. Merges any provided kwargs
3. Delegates to the shared `make_settings()` function

Example from `test_bot.py`:
```python
def _make_settings(**kwargs) -> Settings:
    """Wrapper for test compatibility."""
    defaults = dict(
        telegram_bot_token="test-token",
        openai_api_key="test-key",
    )
    defaults.update(kwargs)
    return make_settings(**defaults)
```

This allows tests to override defaults while reusing the mapping logic:
```python
# Uses defaults
settings = _make_settings()

# Override specific values
settings = _make_settings(telegram_allowed_user_ids=[1, 2, 3])
```

## Error Handling

The `make_settings()` function will raise a `TypeError` if any unexpected keyword arguments are passed:
```python
make_settings(invalid_param="value")
# Raises: TypeError: Unexpected keyword arguments: invalid_param
```

This helps catch typos and unexpected parameters early in tests.

## Backward Compatibility

The Settings class retains backward-compatible properties:
- `settings.telegram_bot_token` → returns `settings.telegram.bot_token`
- `settings.openai_api_key` → returns `settings.openai.api_key`
- etc.

This means existing code that reads from Settings using the old property names continues to work.

## Files Modified

1. **`tests/conftest.py`** (NEW)
   - 91 lines
   - Core mapping logic for legacy-to-new Settings structure

2. **`tests/test_bot.py`**
   - Added import: `from tests.conftest import make_settings`
   - Updated `_make_settings()` to call shared function

3. **`tests/test_llm_client.py`**
   - Added import: `from tests.conftest import make_settings`
   - Updated `_make_settings()` to call shared function

4. **`tests/test_proposals.py`**
   - Added import: `from tests.conftest import make_settings`
   - Updated `_make_settings()` to call shared function

5. **`tests/test_thread_memory.py`**
   - Added import: `from tests.conftest import make_settings`
   - Updated `_make_settings()` to call shared function

6. **`tests/test_tools.py`**
   - Added import: `from tests.conftest import make_settings`
   - Updated `_make_llm_settings()` to call shared function

## Testing

To verify the changes work:
```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_bot.py -v

# Run specific test
pytest tests/test_bot.py::TestIsAllowed::test_allowlist_accepts_known_user -v
```

All tests should pass with these changes as the Settings class:
1. Accepts the new nested structure from `make_settings()`
2. Provides backward-compatible properties for old code