feat(config): let multi-LLM members configure litellmrouter config + Vertex SA key (#2401)

Follow-up to #2384. That PR let an indexed multi-LLM member carry its own
Vertex AI project/region, but two parity gaps remained vs the primary provider:

- A `litellmrouter` member had no per-member router config, so it silently fell
  back to the global `HINDSIGHT_API_LLM_LITELLMROUTER_CONFIG` — a chain could not
  fail over between differently-routed LiteLLM routers (same bug class #2384 fixed
  for Vertex).
- A `vertexai` member used only the global service-account key, so cross-project
  failover with distinct credentials was impossible (project/region alone weren't
  enough).

Adds `litellmrouter_config` and `vertexai_service_account_key` to
`LLMMemberConfig`, reads `{prefix}LLM_{n}_LITELLMROUTER_CONFIG` /
`_VERTEXAI_SERVICE_ACCOUNT_KEY` in `_parse_llm_members`, threads both through
`_member_to_llm`, and lets `LLMProvider.__init__` take a per-instance Vertex SA
key (explicit wins, else global fallback). Single-LLM/global behavior unchanged.

Tests: parse (incl. per-op prefix + invalid-JSON), and build-path proving the
member's own values reach `litellm.Router` and the Vertex SDK client. Docs table
updated with the new per-member keys.

Author: nicoloboschi

hindsight-api-slim/hindsight_api/config.py

@@ -1322,6 +1322,8 @@ class LLMMemberConfig:
     gemini_service_tier: str | None
     vertexai_project_id: str | None = None
     vertexai_region: str | None = None
+    vertexai_service_account_key: str | None = None
+    litellmrouter_config: dict | None = None
 
 
 # Valid multi-LLM strategy modes.
@@ -1417,6 +1419,8 @@ def _parse_llm_members(prefix: str) -> list[LLMMemberConfig]:
                 ),
                 vertexai_project_id=os.getenv(base + "VERTEXAI_PROJECT_ID") or None,
                 vertexai_region=os.getenv(base + "VERTEXAI_REGION") or None,
+                vertexai_service_account_key=os.getenv(base + "VERTEXAI_SERVICE_ACCOUNT_KEY") or None,
+                litellmrouter_config=_parse_llm_router_config(base + "LITELLMROUTER_CONFIG"),
             )
         )
         index += 1

hindsight-api-slim/hindsight_api/engine/llm_wrapper.py

@@ -508,6 +508,7 @@ def __init__(
         gemini_service_tier: str | None = None,
         vertexai_project_id: str | None = None,
         vertexai_region: str | None = None,
+        vertexai_service_account_key: str | None = None,
     ):
         """
         Initialize LLM provider.
@@ -539,6 +540,10 @@ def __init__(
                 chain). When None, falls back to ``HindsightConfig.llm_vertexai_project_id``.
             vertexai_region: Vertex AI region for ``provider="vertexai"``. When None, falls back to
                 ``HindsightConfig.llm_vertexai_region`` (then ``"us-central1"``).
+            vertexai_service_account_key: Path to a Vertex AI service-account key file for
+                ``provider="vertexai"``. Lets a member target a project with its own credentials
+                (e.g. cross-project failover). When None, falls back to
+                ``HindsightConfig.llm_vertexai_service_account_key`` (then ADC).
         """
         self.provider = provider.lower()
         self.api_key = api_key
@@ -646,7 +651,7 @@ def __init__(
                 )
 
             vertexai_region = vertexai_region or config.llm_vertexai_region or "us-central1"
-            service_account_key = config.llm_vertexai_service_account_key
+            service_account_key = vertexai_service_account_key or config.llm_vertexai_service_account_key
 
             # Load explicit service account credentials if provided
             if service_account_key:

hindsight-api-slim/hindsight_api/engine/memory_engine.py

@@ -390,7 +390,8 @@ def _member_to_llm(member: "LLMMemberConfig", config: HindsightConfig) -> LLMCon
     """Build an LLMProvider from one indexed multi-LLM member.
 
     Member fields are self-contained; reasoning_effort falls back to the global
-    setting and default_headers falls back inside ``LLMProvider`` when unset.
+    setting and default_headers / litellmrouter_config / vertexai credentials fall
+    back inside ``LLMProvider`` when unset.
     """
     return LLMConfig(
         provider=member.provider,
@@ -404,6 +405,8 @@ def _member_to_llm(member: "LLMMemberConfig", config: HindsightConfig) -> LLMCon
         gemini_service_tier=member.gemini_service_tier,
         vertexai_project_id=member.vertexai_project_id,
         vertexai_region=member.vertexai_region,
+        vertexai_service_account_key=member.vertexai_service_account_key,
+        litellmrouter_config=member.litellmrouter_config,
     )
 
 

hindsight-api-slim/tests/test_multi_llm_config.py

@@ -113,6 +113,49 @@ def test_parse_members_without_vertexai_fields_default_none(clean_llm_env):
     members = _parse_llm_members("")
     assert members[0].vertexai_project_id is None
     assert members[0].vertexai_region is None
+    assert members[0].vertexai_service_account_key is None
+    assert members[0].litellmrouter_config is None
+
+
+def test_parse_members_vertexai_service_account_key(clean_llm_env):
+    # A vertexai member can carry its own service-account key for cross-project
+    # failover (credentials are otherwise global).
+    clean_llm_env.setenv("HINDSIGHT_API_LLM_1_PROVIDER", "vertexai")
+    clean_llm_env.setenv("HINDSIGHT_API_LLM_1_VERTEXAI_PROJECT_ID", "p")
+    clean_llm_env.setenv("HINDSIGHT_API_LLM_1_VERTEXAI_SERVICE_ACCOUNT_KEY", "/keys/sa.json")
+    members = _parse_llm_members("")
+    assert members[0].vertexai_service_account_key == "/keys/sa.json"
+
+
+def test_parse_members_litellmrouter_config(clean_llm_env):
+    # A litellmrouter member can carry its own router config so a chain can fail
+    # over between differently-routed LiteLLM routers.
+    clean_llm_env.setenv("HINDSIGHT_API_LLM_1_PROVIDER", "litellmrouter")
+    clean_llm_env.setenv(
+        "HINDSIGHT_API_LLM_1_LITELLMROUTER_CONFIG",
+        '{"model_list": [{"model_name": "m"}]}',
+    )
+    members = _parse_llm_members("")
+    assert members[0].litellmrouter_config == {"model_list": [{"model_name": "m"}]}
+
+
+def test_parse_members_litellmrouter_config_per_op_prefix(clean_llm_env):
+    clean_llm_env.setenv("HINDSIGHT_API_REFLECT_LLM_1_PROVIDER", "litellmrouter")
+    clean_llm_env.setenv(
+        "HINDSIGHT_API_REFLECT_LLM_1_LITELLMROUTER_CONFIG",
+        '{"model_list": [{"model_name": "reflect-m"}]}',
+    )
+    reflect = _parse_llm_members("REFLECT_")
+    assert reflect[0].litellmrouter_config == {"model_list": [{"model_name": "reflect-m"}]}
+    # Scoped to the prefix; the global chain is unaffected.
+    assert _parse_llm_members("") == []
+
+
+def test_parse_members_litellmrouter_config_invalid_json_raises(clean_llm_env):
+    clean_llm_env.setenv("HINDSIGHT_API_LLM_1_PROVIDER", "litellmrouter")
+    clean_llm_env.setenv("HINDSIGHT_API_LLM_1_LITELLMROUTER_CONFIG", "{not json")
+    with pytest.raises(ValueError, match="invalid JSON"):
+        _parse_llm_members("")
 
 
 # ── strategy parsing ───────────────────────────────────────────────────────────
@@ -296,3 +339,101 @@ def __init__(self, **kwargs):
     # Project/region flowed all the way to the Vertex AI SDK client.
     assert captured["project"] == "member-proj"
     assert captured["location"] == "europe-west1"
+
+
+def test_member_to_llm_passes_vertexai_service_account_key(clean_llm_env, monkeypatch):
+    """A vertexai member's own service-account key reaches credential loading.
+
+    The key path flows to ``service_account.Credentials.from_service_account_file``
+    and the resulting credentials reach the Vertex AI SDK client — proving the
+    member value is used rather than the (unset) global one. Both the credential
+    loader and the SDK client are patched so no file or network is touched.
+    """
+    import hindsight_api.engine.llm_wrapper as llm_wrapper
+    import hindsight_api.engine.providers.gemini_llm as gemini_llm
+    from hindsight_api.config import clear_config_cache
+    from hindsight_api.engine.memory_engine import _member_to_llm
+
+    captured: dict = {}
+    sentinel_creds = object()
+
+    class _FakeServiceAccount:
+        class Credentials:
+            @staticmethod
+            def from_service_account_file(path, scopes=None):
+                captured["key_path"] = path
+                return sentinel_creds
+
+    class _FakeClient:
+        def __init__(self, **kwargs):
+            captured.update(kwargs)
+
+    monkeypatch.setattr(llm_wrapper, "VERTEXAI_AVAILABLE", True)
+    monkeypatch.setattr(llm_wrapper, "service_account", _FakeServiceAccount)
+    monkeypatch.setattr(gemini_llm.genai, "Client", _FakeClient)
+    clear_config_cache()
+
+    member = LLMMemberConfig(
+        provider="vertexai",
+        api_key=None,
+        model="gemini-2.0-flash",
+        base_url=None,
+        reasoning_effort=None,
+        extra_body=None,
+        default_headers=None,
+        bedrock_service_tier=None,
+        gemini_service_tier=None,
+        vertexai_project_id="member-proj",
+        vertexai_service_account_key="/keys/member-sa.json",
+    )
+    provider = _member_to_llm(member, _empty_config())
+
+    assert provider.provider == "vertexai"
+    # The member's key path was loaded, and the credentials reached the SDK client.
+    assert captured["key_path"] == "/keys/member-sa.json"
+    assert captured["credentials"] is sentinel_creds
+
+
+# ── litellmrouter member build path (_member_to_llm) ─────────────────────────────
+
+
+def test_member_to_llm_passes_litellmrouter_config(clean_llm_env, monkeypatch):
+    """A litellmrouter member's own router config reaches the LiteLLM router build.
+
+    The global config has no router config, so this also proves the member's
+    config is used (no "requires a config object" error) instead of the global
+    fallback. The LiteLLM router provider is patched so no router is constructed.
+    """
+    import hindsight_api.engine.providers as providers
+    from hindsight_api.config import clear_config_cache
+    from hindsight_api.engine.memory_engine import _member_to_llm
+
+    captured: dict = {}
+
+    class _FakeRouterLLM:
+        provider = "litellmrouter"
+
+        def __init__(self, **kwargs):
+            captured.update(kwargs)
+
+    monkeypatch.setattr(providers, "LiteLLMRouterLLM", _FakeRouterLLM)
+    clear_config_cache()
+
+    router_cfg = {"model_list": [{"model_name": "m"}]}
+    member = LLMMemberConfig(
+        provider="litellmrouter",
+        api_key=None,
+        model="m",
+        base_url=None,
+        reasoning_effort=None,
+        extra_body=None,
+        default_headers=None,
+        bedrock_service_tier=None,
+        gemini_service_tier=None,
+        litellmrouter_config=router_cfg,
+    )
+    provider = _member_to_llm(member, _empty_config())
+
+    assert provider.provider == "litellmrouter"
+    # The member's own router config flowed to the LiteLLM router build.
+    assert captured["config"] == router_cfg

hindsight-docs/docs/developer/configuration.md

@@ -370,6 +370,8 @@ The unindexed `HINDSIGHT_API_LLM_*` config is the **primary** (member 1). Extra
 | `HINDSIGHT_API_LLM_<n>_REASONING_EFFORT` | Reasoning effort for member `n`. | `HINDSIGHT_API_LLM_REASONING_EFFORT` |
 | `HINDSIGHT_API_LLM_<n>_EXTRA_BODY` / `_DEFAULT_HEADERS` | Per-member JSON overrides. | - |
 | `HINDSIGHT_API_LLM_<n>_BEDROCK_SERVICE_TIER` / `_GEMINI_SERVICE_TIER` | Per-member service tier. | - |
+| `HINDSIGHT_API_LLM_<n>_VERTEXAI_PROJECT_ID` / `_VERTEXAI_REGION` / `_VERTEXAI_SERVICE_ACCOUNT_KEY` | Per-member Vertex AI project, region, and service-account key path (for a `vertexai` member). Each falls back to the global `HINDSIGHT_API_LLM_VERTEXAI_*` when unset. | Global / `us-central1` / ADC |
+| `HINDSIGHT_API_LLM_<n>_LITELLMROUTER_CONFIG` | Per-member LiteLLM Router config JSON (for a `litellmrouter` member). Falls back to the global `HINDSIGHT_API_LLM_LITELLMROUTER_CONFIG` when unset. | - |
 | `HINDSIGHT_API_LLM_STRATEGY` | JSON routing strategy across the chain. Unset = single primary LLM (no change). | - |
 
 The strategy JSON supports two modes:

skills/hindsight-docs/references/developer/configuration.md

@@ -370,6 +370,8 @@ The unindexed `HINDSIGHT_API_LLM_*` config is the **primary** (member 1). Extra
 | `HINDSIGHT_API_LLM_<n>_REASONING_EFFORT` | Reasoning effort for member `n`. | `HINDSIGHT_API_LLM_REASONING_EFFORT` |
 | `HINDSIGHT_API_LLM_<n>_EXTRA_BODY` / `_DEFAULT_HEADERS` | Per-member JSON overrides. | - |
 | `HINDSIGHT_API_LLM_<n>_BEDROCK_SERVICE_TIER` / `_GEMINI_SERVICE_TIER` | Per-member service tier. | - |
+| `HINDSIGHT_API_LLM_<n>_VERTEXAI_PROJECT_ID` / `_VERTEXAI_REGION` / `_VERTEXAI_SERVICE_ACCOUNT_KEY` | Per-member Vertex AI project, region, and service-account key path (for a `vertexai` member). Each falls back to the global `HINDSIGHT_API_LLM_VERTEXAI_*` when unset. | Global / `us-central1` / ADC |
+| `HINDSIGHT_API_LLM_<n>_LITELLMROUTER_CONFIG` | Per-member LiteLLM Router config JSON (for a `litellmrouter` member). Falls back to the global `HINDSIGHT_API_LLM_LITELLMROUTER_CONFIG` when unset. | - |
 | `HINDSIGHT_API_LLM_STRATEGY` | JSON routing strategy across the chain. Unset = single primary LLM (no change). | - |
 
 The strategy JSON supports two modes: