Update configuration management and enhance file structure, add test-matrix (#237)

* Update configuration management and enhance file structure

- Refactored configuration file paths to use a dedicated `config/` directory, including updates to `config.yml` and its template.
- Modified service scripts to load the new configuration path for `config.yml`.
- Enhanced `.gitignore` to include the new configuration files and templates.
- Updated documentation to reflect changes in configuration file locations and usage.
- Improved setup scripts to ensure proper creation and management of configuration files.
- Added new test configurations for various provider combinations to streamline testing processes.

* Add test requirements and clean up imports in wizard.py

- Introduced a new `test-requirements.txt` file to manage testing dependencies.
- Removed redundant import of `shutil` in `wizard.py` to improve code clarity.

* Add ConfigManager for unified configuration management

- Introduced a new `config_manager.py` module to handle reading and writing configurations from `config.yml` and `.env` files, ensuring backward compatibility.
- Refactored `ChronicleSetup` in `backends/advanced/init.py` to utilize `ConfigManager` for loading and updating configurations, simplifying the setup process.
- Removed redundant methods for loading and saving `config.yml` directly in `ChronicleSetup`, as these are now managed by `ConfigManager`.
- Enhanced user feedback during configuration updates, including success messages for changes made to configuration files.

* Refactor transcription provider configuration and enhance setup process

- Updated `.env.template` to clarify speech-to-text configuration and removed deprecated options for Mistral.
- Modified `docker-compose.yml` to streamline environment variable management by removing unused Mistral keys.
- Enhanced `ChronicleSetup` in `init.py` to provide clearer user feedback and updated the transcription provider selection process to rely on `config.yml`.
- Improved error handling in the websocket controller to determine the transcription provider from the model registry instead of environment variables.
- Updated health check routes to reflect the new method of retrieving the transcription provider from `config.yml`.
- Adjusted `config.yml.template` to include comments on transcription provider options for better user guidance.

* Enhance ConfigManager with deep merge functionality

- Updated the `update_memory_config` method to perform a deep merge of updates into the memory configuration, ensuring nested dictionaries are merged correctly.
- Added a new `_deep_merge` method to handle recursive merging of dictionaries, improving configuration management capabilities.

* Refactor run-test.sh and enhance memory extraction tests

- Removed deprecated environment variable handling for TRANSCRIPTION_PROVIDER in `run-test.sh`, streamlining the configuration process.
- Introduced a new `run-custom.sh` script for executing Robot tests with custom configurations, improving test flexibility.
- Enhanced memory extraction tests in `audio_keywords.robot` and `memory_keywords.robot` to include detailed assertions and result handling.
- Updated `queue_keywords.robot` to fail fast if a job is in a 'failed' state when expecting 'completed', improving error handling.
- Refactored `test_env.py` to load environment variables with correct precedence, ensuring better configuration management.

* unify tests to robot test, add some more clean up

* Update health check configuration in docker-compose-test.yml (#241)

- Increased the number of retries from 5 to 10 for improved resilience during service readiness checks.
- Extended the start period from 30s to 60s to allow more time for services to initialize before health checks commence.

* Add step to create test configuration file in robot-tests.yml

- Introduced a new step in the GitHub Actions workflow to copy the test configuration file from tests/configs/deepgram-openai.yml to a new config/config.yml.
- Added logging to confirm the creation of the test config file, improving visibility during the test setup process.

* remove cache step since not required

* coderabbit comments

* Refactor ConfigManager error handling for configuration file loading

- Updated the ConfigManager to raise RuntimeError exceptions when the configuration file is not found or is invalid, improving error visibility and user guidance.
- Removed fallback behavior that previously returned the current directory, ensuring users are explicitly informed about missing or invalid configuration files.

* Refactor _find_repo_root method in ConfigManager

- Updated the _find_repo_root method to locate the repository root using the __file__ location instead of searching for config/config.yml, simplifying the logic and improving reliability.
- Removed the previous error handling that raised a RuntimeError if the configuration file was not found, as the new approach assumes config_manager.py is always at the repo root.

Author: AnkushMalaker

.github/workflows/README.md

@@ -86,6 +86,6 @@ uv sync --dev
 cp .env.template .env.test
 # Add your API keys to .env.test
 
-# Run test (modify CACHED_MODE in test_integration.py if needed)
-uv run pytest test_integration.py::test_full_pipeline_integration -v -s
+# Run Robot Framework integration tests
+uv run robot --outputdir test-results --loglevel INFO tests/integration/integration_test.robot
 ```

.github/workflows/robot-tests.yml

@@ -61,7 +61,6 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: "3.12"
-        cache: 'pip'
 
     - name: Install uv
       uses: astral-sh/setup-uv@v4
@@ -94,6 +93,14 @@ jobs:
         TEST_DEVICE_NAME=robot-test
         EOF
 
+    - name: Create test config.yml
+      run: |
+        echo "Copying test configuration file..."
+        mkdir -p config
+        cp tests/configs/deepgram-openai.yml config/config.yml
+        echo "✓ Test config.yml created from tests/configs/deepgram-openai.yml"
+        ls -lh config/config.yml
+
     - name: Start test environment
       working-directory: backends/advanced
       env:

.gitignore

@@ -4,8 +4,16 @@
 !**/.env.template
 **/memory_config.yaml
 !**/memory_config.yaml.template
-config.yml
-!config.yml.template
+tests/setup/.env.test
+
+# Main config (user-specific)
+config/config.yml
+!config/config.yml.template
+
+# Config backups
+config/*.backup.*
+config/*.backup*
+
 example/*
 **/node_modules/*
 **/ollama-data/*

CLAUDE.md

@@ -116,11 +116,11 @@ cp .env.template .env  # Configure API keys
 
 # Manual test execution (for debugging)
 source .env && export DEEPGRAM_API_KEY && export OPENAI_API_KEY
-uv run pytest tests/test_integration.py::test_full_pipeline_integration -v -s
+uv run robot --outputdir test-results --loglevel INFO ../../tests/integration/integration_test.robot
 
 # Leave test containers running for debugging (don't auto-cleanup)
 CLEANUP_CONTAINERS=false source .env && export DEEPGRAM_API_KEY && export OPENAI_API_KEY
-uv run pytest tests/test_integration.py::test_full_pipeline_integration -v -s
+uv run robot --outputdir test-results --loglevel INFO ../../tests/integration/integration_test.robot
 
 # Manual cleanup when needed
 docker compose -f docker-compose-test.yml down -v
@@ -390,7 +390,7 @@ docker compose up --build -d
 
 ### Testing Strategy
 - **Local Test Scripts**: Simplified scripts (`./run-test.sh`) mirror CI workflows for local development
-- **End-to-End Integration**: `test_integration.py` validates complete audio processing pipeline
+- **End-to-End Integration**: Robot Framework tests (`tests/integration/integration_test.robot`) validate complete audio processing pipeline
 - **Speaker Recognition Tests**: `test_speaker_service_integration.py` validates speaker identification
 - **Environment Flexibility**: Tests work with both local .env files and CI environment variables
 - **Automated Cleanup**: Test containers are automatically removed after execution

Docs/getting-started.md

@@ -179,9 +179,9 @@ After configuration, verify everything works with the integration test suite:
 
 # Alternative: Manual test with detailed logging
 source .env && export DEEPGRAM_API_KEY OPENAI_API_KEY && \
-  uv run pytest tests/test_integration.py -vv -s --log-cli-level=INFO
+  uv run robot --outputdir ../../test-results --loglevel INFO ../../tests/integration/integration_test.robot
 ```
-This end-to-end test validates the complete audio processing pipeline.
+This end-to-end test validates the complete audio processing pipeline using Robot Framework.
 
 ## Using the System
 
@@ -342,7 +342,7 @@ curl -X POST "http://localhost:8000/api/process-audio-files" \
 
 **Implementation**: 
 - **Memory System**: `src/advanced_omi_backend/memory/memory_service.py` + `src/advanced_omi_backend/controllers/memory_controller.py`
-- **Configuration**: memory settings in `config.yml` (memory section)
+- **Configuration**: memory settings in `config/config.yml` (memory section)
 
 ### Authentication & Security
 - **Email Authentication**: Login with email and password
@@ -541,10 +541,10 @@ OPENMEMORY_MCP_URL=http://host.docker.internal:8765
 
 > 🎯 **New to memory configuration?** Read our [Memory Configuration Guide](./memory-configuration-guide.md) for a step-by-step setup guide with examples.
 
-The system uses **centralized configuration** via `config.yml` for all models (LLM, embeddings, vector store) and memory extraction settings.
+The system uses **centralized configuration** via `config/config.yml` for all models (LLM, embeddings, vector store) and memory extraction settings.
 
 ### Configuration File Location
-- **Path**: repository `config.yml` (override with `CONFIG_FILE` env var)
+- **Path**: repository `config/config.yml` (override with `CONFIG_FILE` env var)
 - **Hot-reload**: Changes are applied on next processing cycle (no restart required)
 - **Fallback**: If file is missing, system uses safe defaults with environment variables
 
@@ -613,7 +613,7 @@ If you experience JSON parsing errors in fact extraction:
 
 2. **Enable fact extraction** with reliable JSON output:
    ```yaml
-   # In config.yml (memory section)
+   # In config/config.yml (memory section)
    fact_extraction:
      enabled: true  # Safe to enable with GPT-4o
    ```
@@ -727,5 +727,5 @@ curl -H "Authorization: Bearer $ADMIN_TOKEN" \
 - **Connect audio clients** using the WebSocket API
 - **Explore the dashboard** to manage conversations and users
 - **Review the user data architecture** for understanding data organization
-- **Customize memory extraction** by editing the `memory` section in `config.yml`
+- **Customize memory extraction** by editing the `memory` section in `config/config.yml`
 - **Monitor processing performance** using debug API endpoints

backends/advanced/.env.template

@@ -45,18 +45,14 @@ OPENAI_MODEL=gpt-4o-mini
 # CHAT_TEMPERATURE=0.7
 
 # ========================================
-# SPEECH-TO-TEXT CONFIGURATION (Choose one)
+# SPEECH-TO-TEXT CONFIGURATION (API Keys Only)
 # ========================================
+# Provider selection is in config.yml (defaults.stt)
 
-# Option 1: Deepgram (recommended for best transcription quality)
+# Deepgram (cloud-based, recommended)
 DEEPGRAM_API_KEY=
 
-# Option 2: Parakeet ASR service from extras/asr-services
-# PARAKEET_ASR_URL=http://host.docker.internal:8767
-
-# Optional: Specify which provider to use ('deepgram' or 'parakeet')
-# If not set, will auto-select based on available configuration (Deepgram preferred)
-# TRANSCRIPTION_PROVIDER=
+# Note: Parakeet ASR URL configured in config.yml
 
 # ========================================
 # SPEECH DETECTION CONFIGURATION

backends/advanced/Docs/README.md

@@ -13,7 +13,7 @@ Welcome to chronicle! This guide provides the optimal reading sequence to unders
 - What the system does (voice → memories)
 - Key features and capabilities
 - Basic setup and configuration
-- **Code References**: `src/advanced_omi_backend/main.py`, `config.yml`, `docker-compose.yml`
+- **Code References**: `src/advanced_omi_backend/main.py`, `config/config.yml`, `docker-compose.yml`
 
 ### 2. **[System Architecture](./architecture.md)** 
 **Read second** - Complete technical architecture with diagrams
@@ -70,7 +70,7 @@ Welcome to chronicle! This guide provides the optimal reading sequence to unders
 
 ## 🔍 **Configuration & Customization**
 
-### 6. **Configuration File** → `../config.yml`
+### 6. **Configuration File** → `../config/config.yml`
 **Central configuration for all extraction**
 - Memory extraction settings and prompts
 - Quality control and debug settings
@@ -86,11 +86,11 @@ Welcome to chronicle! This guide provides the optimal reading sequence to unders
 1. [quickstart.md](./quickstart.md) - System overview
 2. [architecture.md](./architecture.md) - Technical architecture  
 3. `src/advanced_omi_backend/main.py` - Core imports and setup
-4. `config.yml` - Configuration overview
+4. `config/config.yml` - Configuration overview
 
 ### **"I want to work on memory extraction"**
 1. [memories.md](./memories.md) - Memory system details
-2. `../config.yml` - Models and memory configuration
+2. `../config/config.yml` - Models and memory configuration
 3. `src/advanced_omi_backend/memory/memory_service.py` - Implementation
 4. `src/advanced_omi_backend/controllers/memory_controller.py` - Processing triggers
 
@@ -130,7 +130,7 @@ backends/advanced-backend/
 │   │   └── memory_service.py      # Memory system (Mem0)
 │   └── model_registry.py          # Configuration loading
 │
-├── config.yml                     # 📋 Central configuration
+├── config/config.yml                     # 📋 Central configuration
 ├── MEMORY_DEBUG_IMPLEMENTATION.md # Debug system details
 ```
 
@@ -148,7 +148,7 @@ backends/advanced-backend/
 
 ### **Configuration**
 - **Loading**: `src/advanced_omi_backend/model_registry.py`
-- **File**: `config.yml`
+- **File**: `config/config.yml`
 - **Usage**: `src/advanced_omi_backend/memory/memory_service.py`
 
 ### **Authentication**
@@ -162,7 +162,7 @@ backends/advanced-backend/
 
 1. **Follow the references**: Each doc links to specific code files and line numbers
 2. **Use the debug API**: `GET /api/debug/memory/stats` shows live system status
-3. **Check configuration first**: Many behaviors are controlled by `config.yml`
+3. **Check configuration first**: Many behaviors are controlled by `config/config.yml`
 4. **Understand the memory pipeline**: Memories (end-of-conversation)
 5. **Test with curl**: All API endpoints have curl examples in the docs
 
@@ -175,20 +175,20 @@ backends/advanced-backend/
 1. **Set up the system**: Follow [quickstart.md](./quickstart.md) to get everything running
 2. **Test the API**: Use the curl examples in the documentation to test endpoints
 3. **Explore the debug system**: Check `GET /api/debug/memory/stats` to see live data
-4. **Modify configuration**: Edit `config.yml` (memory section) to see how it affects extraction
+4. **Modify configuration**: Edit `config/config.yml` (memory section) to see how it affects extraction
 5. **Read the code**: Start with `src/advanced_omi_backend/main.py` and follow the references in each doc
 
 ### **Contributing Guidelines**
 
 - **Add code references**: When updating docs, include file paths and line numbers
 - **Test your changes**: Use the debug API to verify your modifications work
-- **Update configuration**: Add new settings to `config.yml` when needed
+- **Update configuration**: Add new settings to `config/config.yml` when needed
 - **Follow the architecture**: Keep memories in their respective services
 
 ### **Getting Help**
 
 - **Debug API**: `GET /api/debug/memory/*` endpoints show real-time system status
-- **Configuration**: Check `config.yml` for behavior controls
+- **Configuration**: Check `config/config.yml` for behavior controls
 - **Logs**: Check Docker logs with `docker compose logs chronicle-backend`
 - **Documentation**: Each doc file links to relevant code sections
 

backends/advanced/Docs/contribution.md

@@ -1,12 +1,12 @@
   1. Docs/quickstart.md (15 min)
   2. Docs/architecture.md (20 min)
   3. main.py - just the imports and WebSocket sections (15 min)
-  4. config.yml (memory section) (10 min)
+  4. config/config.yml (memory section) (10 min)
 
   🔧 "I want to work on memory extraction"
 
   1. Docs/quickstart.md → Docs/memories.md
-  2. config.yml (memory.extraction section)
+  2. config/config.yml (memory.extraction section)
   3. main.py lines 1047-1065 (trigger)
   4. main.py lines 1163-1195 (processing)
   5. src/memory/memory_service.py

backends/advanced/Docs/memories.md

@@ -10,7 +10,7 @@ This document explains how to configure and customize the memory service in the
 - **Repository Layer**: `src/advanced_omi_backend/conversation_repository.py` (clean data access)
 - **Processing Manager**: `src/advanced_omi_backend/processors.py` (MemoryProcessor class)
 - **Conversation Management**: `src/advanced_omi_backend/conversation_manager.py` (lifecycle coordination)
-- **Configuration**: `config.yml` (memory section) + `src/model_registry.py`
+- **Configuration**: `config/config.yml` (memory section) + `src/model_registry.py`
 
 ## Overview
 
@@ -180,7 +180,7 @@ OPENAI_MODEL=gpt-5-mini  # Recommended for reliable JSON output
 # OPENAI_MODEL=gpt-3.5-turbo  # Budget option
 ```
 
-Or configure via `config.yml` (memory block):
+Or configure via `config/config.yml` (memory block):
 
 ```yaml
 memory_extraction:

backends/advanced/Docs/memory-configuration-guide.md

@@ -6,10 +6,10 @@ This guide helps you set up and configure the memory system for the Friend Advan
 
 1. **Copy the template configuration**:
 ```bash
-Edit the `memory` section of `config.yml`.
+Edit the `memory` section of `config/config.yml`.
 ```
 
-2. **Edit `config.yml`** with your preferred settings in the `memory` section:
+2. **Edit `config/config.yml`** with your preferred settings in the `memory` section:
 ```yaml
 memory:
   provider: "mem0"  # or "basic" for simpler setup
@@ -127,6 +127,6 @@ memory:
 
 ## Next Steps
 
-- Configure action items detection in `config.yml` (memory.extraction)
+- Configure action items detection in `config/config.yml` (memory.extraction)
 - Set up custom prompt templates for your use case
 - Monitor memory processing in the debug dashboard