Context
PR #238 surfaced that store_user_facts fails when the environment's default fact-extraction model is unavailable or misconfigured. The failure occurs at the litellm.completion() call, not in the persistence path, making it hard to diagnose without knowing the configuration surface.
Problem
The three LLM-backed features — guidelines generation, conflict resolution, and fact extraction — each rely on a model setting in altk_evolve/config/llm.py (LLMSettings), but the required environment variables and their fallback chain are not documented:
| Setting |
Env var |
Fallback |
guidelines_model |
EVOLVE_GUIDELINES_MODEL |
EVOLVE_TIPS_MODEL → EVOLVE_MODEL_NAME → gpt-4o |
conflict_resolution_model |
EVOLVE_CONFLICT_RESOLUTION_MODEL |
EVOLVE_MODEL_NAME → gpt-4o |
fact_extraction_model |
EVOLVE_FACT_EXTRACTION_MODEL |
EVOLVE_MODEL_NAME → gpt-4o |
custom_llm_provider |
EVOLVE_CUSTOM_LLM_PROVIDER |
auto-detects openai if OPENAI_BASE_URL or OPENAI_API_KEY is set |
Suggested scope
- Add a configuration reference (README section or dedicated doc) covering these env vars.
- Consider surfacing a clearer error when a model is not reachable, rather than the generic
Failed to parse extracted facts response after 3 retries.
Ref
Context
PR #238 surfaced that
store_user_factsfails when the environment's default fact-extraction model is unavailable or misconfigured. The failure occurs at thelitellm.completion()call, not in the persistence path, making it hard to diagnose without knowing the configuration surface.Problem
The three LLM-backed features — guidelines generation, conflict resolution, and fact extraction — each rely on a model setting in
altk_evolve/config/llm.py(LLMSettings), but the required environment variables and their fallback chain are not documented:guidelines_modelEVOLVE_GUIDELINES_MODELEVOLVE_TIPS_MODEL→EVOLVE_MODEL_NAME→gpt-4oconflict_resolution_modelEVOLVE_CONFLICT_RESOLUTION_MODELEVOLVE_MODEL_NAME→gpt-4ofact_extraction_modelEVOLVE_FACT_EXTRACTION_MODELEVOLVE_MODEL_NAME→gpt-4ocustom_llm_providerEVOLVE_CUSTOM_LLM_PROVIDERopenaiifOPENAI_BASE_URLorOPENAI_API_KEYis setSuggested scope
Failed to parse extracted facts responseafter 3 retries.Ref