Skip to content

CONFIGURATION.md

Latest commit

 

History

History
247 lines (182 loc) · 7.23 KB

CONFIGURATION.md

File metadata and controls

247 lines (182 loc) · 7.23 KB
Raw

Configuration Guide

Overview

The orchestrator follows a strict no-defaults policy for configuration. All configuration values must be explicitly provided via environment variables in the .env file. This ensures:

  • Explicit configuration: No hidden assumptions or defaults
  • Fail-fast behavior: Missing configuration is detected immediately at startup
  • Environment-specific settings: Easy to configure for dev/test/prod environments
  • Secure secrets: Sensitive values are never hardcoded

Quick Start

  1. Copy the example configuration:

    cp .env.example .env

  2. Edit .env and fill in all required values

  3. Verify configuration loads:

    uv run python -c "from src.talk2yourdata_mcp.config import get_config; get_config()"

Configuration Categories

LLM Configuration (REQUIRED)

Controls the language model behavior.

LLM_API_URL=https://llm.ext.icrc.org/
LLM_API_KEY=your-api-key-here
LLM_MODEL_NAME=gpt-4o              # Main model for complex reasoning
LLM_SMALL_MODEL_NAME=gpt-4o-mini   # Cost-optimized model for simple tasks
LLM_MAX_TOKENS=1000                # Maximum tokens per LLM call
LLM_TEMPERATURE=0.7                # Creativity level (0.0-1.0)

Notes:

  • LLM_MODEL_NAME: Used for intent extraction, query decomposition, etc.
  • LLM_SMALL_MODEL_NAME: Used for simple yes/no decisions (e.g., ambiguity detection)
  • Lower temperature (0.0-0.3) = more deterministic, higher (0.7-1.0) = more creative

Workflow Configuration (REQUIRED)

Controls orchestrator workflow behavior.

MAX_STEPS=20                       # Maximum graph execution steps before timeout
MAX_REFINEMENT_LOOPS=3             # Maximum conversational refinement iterations
ENABLE_VALIDATION=true             # Whether to validate DHIS2 parameters
ENABLE_CACHING=true                # Whether to cache MCP tool results

Notes:

  • MAX_STEPS: Prevents infinite loops in the state graph
  • MAX_REFINEMENT_LOOPS: Limits back-and-forth for query clarification
  • ENABLE_VALIDATION: Set to false to skip Part C validation (faster, less robust)

Logging Configuration (REQUIRED)

Controls logging behavior.

LOG_LEVEL=INFO                     # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_TO_FILE=false                  # Whether to write logs to file
LOG_FILE_PATH=orchestrator.log     # Log file path (if LOG_TO_FILE=true)

Common LOG_LEVEL values:

  • DEBUG: Very verbose, includes LLM prompts/responses
  • INFO: Normal operation, shows workflow progress
  • WARNING: Only warnings and errors (recommended for production)
  • ERROR: Only errors

MCP Server Configuration (REQUIRED)

Controls the DHIS2 MCP server connection.

MCP_SERVER_COMMAND=uv
# MCP_SERVER_ARGS is optional, defaults to proper uv run command

Notes:

  • Default MCP_SERVER_ARGS: run,--env-file,.env,--,mcp,run,src/talk2yourdata_mcp/server.py
  • Only override if you need custom MCP server launch parameters

Query Processing Configuration (REQUIRED)

Controls MCP tool execution behavior.

PARALLEL_TOOL_EXECUTION=false      # Parallel MCP tool calls (experimental)
TOOL_TIMEOUT_SECONDS=30            # Timeout for individual MCP tool calls

Notes:

  • PARALLEL_TOOL_EXECUTION=true is experimental and may cause race conditions
  • Increase TOOL_TIMEOUT_SECONDS if DHIS2 API is slow

Ambiguity Handling (REQUIRED)

Controls handling of ambiguous search results.

MAX_AMBIGUOUS_RESULTS=5            # Maximum ambiguous results to show user
AUTO_SELECT_SINGLE_RESULT=true     # Auto-select when only 1 result found

Notes:

  • When searches return multiple matches, user is prompted to choose
  • AUTO_SELECT_SINGLE_RESULT=true skips prompt when only one match exists

Validation Configuration (REQUIRED)

Controls DHIS2 parameter validation behavior (Part C).

VALIDATION_SAMPLE_SIZE=10          # Rows to fetch in validation queries
REQUIRE_DATA_IN_VALIDATION=true    # Whether to require actual data

Notes:

  • VALIDATION_SAMPLE_SIZE: Small queries are fast, large queries more thorough
  • REQUIRE_DATA_IN_VALIDATION=false: Accept parameters even if no data exists

Performance Configuration (REQUIRED)

Controls caching and metrics collection.

CACHE_TTL_SECONDS=300              # Cache lifetime (5 minutes)
ENABLE_METRICS=false               # Collect performance metrics

Notes:

  • Caching improves response time for repeated queries
  • Metrics collection adds minimal overhead

Error Handling

Missing Required Configuration

If a required environment variable is missing, the orchestrator will fail immediately with a clear error message:

ConfigurationError: Missing required environment variable: LLM_API_KEY
Please set LLM_API_KEY in your .env file or environment.

Invalid Configuration Values

If a configuration value has the wrong type or format:

ConfigurationError: Invalid integer value for MAX_STEPS: abc

ConfigurationError: Invalid boolean value for ENABLE_CACHING: maybe
Must be one of: true, false, 1, 0, yes, no, on, off

Best Practices

Development Environment

LOG_LEVEL=DEBUG                    # See detailed execution
ENABLE_VALIDATION=true             # Catch issues early
ENABLE_CACHING=false               # Always fresh results during testing
MAX_STEPS=50                       # Higher limit for experimentation

Production Environment

LOG_LEVEL=WARNING                  # Only errors and warnings
ENABLE_VALIDATION=true             # Robust parameter validation
ENABLE_CACHING=true                # Better performance
MAX_STEPS=20                       # Prevent runaway processes
ENABLE_METRICS=true                # Track performance over time

Testing Environment

LOG_LEVEL=ERROR                    # Minimal output during tests
ENABLE_VALIDATION=false            # Skip validation for unit tests
ENABLE_CACHING=false               # Predictable test behavior
TOOL_TIMEOUT_SECONDS=5             # Fast failure on issues

Configuration Validation

To verify your configuration is correct:

# Quick check
uv run python -c "from src.talk2yourdata_mcp.config import get_config; get_config()"

# Detailed inspection
uv run python -c "from src.talk2yourdata_mcp.config import get_config; import pprint; pprint.pprint(vars(get_config()))"

Programmatic Access

from src.talk2yourdata_mcp.config import get_config, ConfigurationError

try:
    config = get_config()
    print(f"Using model: {config.llm_model_name}")
    print(f"Max steps: {config.max_steps}")
except ConfigurationError as e:
    print(f"Configuration error: {e}")
    exit(1)

Migration from Old Configuration

If you're upgrading from the old hardcoded configuration, add these new required variables to your .env:

# New in refactoring
LLM_SMALL_MODEL_NAME=gpt-4o-mini
LLM_MAX_TOKENS=1000
LLM_TEMPERATURE=0.7
MAX_STEPS=20
MAX_REFINEMENT_LOOPS=3
ENABLE_VALIDATION=true
ENABLE_CACHING=true
LOG_TO_FILE=false
LOG_FILE_PATH=orchestrator.log
MCP_SERVER_COMMAND=uv
PARALLEL_TOOL_EXECUTION=false
TOOL_TIMEOUT_SECONDS=30
MAX_AMBIGUOUS_RESULTS=5
AUTO_SELECT_SINGLE_RESULT=true
VALIDATION_SAMPLE_SIZE=10
REQUIRE_DATA_IN_VALIDATION=true
CACHE_TTL_SECONDS=300
ENABLE_METRICS=false