Merge pull request #26 from MachineWisdomAI/docs/llm-provider-clarification

docs: clarify LLM provider support with any-llm-sdk and multi-provider extensibility

Author: timeleft--

AGENTS_SETUP_INSTRUCTIONS.md

@@ -20,9 +20,11 @@ pip install fava-trails
 git clone https://github.com/MachineWisdomAI/fava-trails.git && cd fava-trails && uv sync
 ```
 
-### OpenRouter API Key (for Trust Gate)
+### LLM Configuration (for Trust Gate)
 
-The Trust Gate reviews thoughts before promotion using an LLM via [OpenRouter](https://openrouter.ai/).
+The Trust Gate reviews thoughts before promotion using an LLM. By default, FAVA Trails uses [OpenRouter](https://openrouter.ai/) for unified access to 100+ models.
+
+**OpenRouter (default, recommended):**
 
 1. Create a free account at https://openrouter.ai/
 2. Generate an API key at https://openrouter.ai/keys
@@ -31,6 +33,8 @@ The Trust Gate reviews thoughts before promotion using an LLM via [OpenRouter](h
 
 The default model (`google/gemini-2.5-flash`) costs ~$0.001 per review.
 
+**Other providers:** FAVA Trails uses [any-llm-sdk](https://github.com/marekstephens/any-llm-sdk) for unified LLM access, enabling support for additional providers (Anthropic, OpenAI, Bedrock, etc.). Configuration for provider selection will be available in future versions via `config.yaml`.
+
 ## Creating the Data Repo
 
 The data repo is a plain git repository that the MCP server JJ-colocates on first use. It holds your organization's trail data — separate from the engine.
@@ -148,7 +152,7 @@ trails:
 | `push_strategy` | string | `manual` | `immediate` auto-pushes after writes; `manual` requires explicit sync |
 | `trust_gate` | string | `llm-oneshot` | Global trust gate policy |
 | `trust_gate_model` | string | `google/gemini-2.5-flash` | Model for LLM-based trust review |
-| `openrouter_api_key_env` | string | `OPENROUTER_API_KEY` | Env var name holding the API key |
+| `openrouter_api_key_env` | string | `OPENROUTER_API_KEY` | Env var name holding the API key for OpenRouter (default provider) |
 | `hooks` | list | `[]` | Lifecycle hook entries (see [Lifecycle Hooks](#lifecycle-hooks)) |
 
 ### Per-Trail Config

README.md

@@ -120,7 +120,7 @@ For Claude Desktop on Windows (accessing WSL):
 }
 ```
 
-> The Trust Gate uses [OpenRouter](https://openrouter.ai/) to review thoughts before promotion. Get a free API key at [openrouter.ai/keys](https://openrouter.ai/keys). The default model (`google/gemini-2.5-flash`) costs ~$0.001 per review.
+> **The Trust Gate uses LLM verification:** Thoughts are reviewed before promotion to ensure they're coherent and safe. By default, FAVA Trails uses [OpenRouter](https://openrouter.ai/) to access 100+ models from Anthropic, OpenAI, Google, Qwen, and others. Get a free API key at [openrouter.ai/keys](https://openrouter.ai/keys). The default model (`google/gemini-2.5-flash`) costs ~$0.001 per review. Multi-provider support via [any-llm-sdk](https://github.com/marekstephens/any-llm-sdk) enables switching to other providers by modifying `config.yaml`.
 
 ### Use it
 
@@ -201,7 +201,9 @@ Environment variables:
 | `FAVA_TRAILS_DIR` | Server | Override trails directory location (absolute path) | `$FAVA_TRAILS_DATA_REPO/trails` |
 | `FAVA_TRAILS_SCOPE_HINT` | Server | Broad scope hint baked into tool descriptions | *(none)* |
 | `FAVA_TRAILS_SCOPE` | Agent | Project-specific scope from `.env` file | *(none)* |
-| `OPENROUTER_API_KEY` | Server | API key for Trust Gate LLM reviews ([get one](https://openrouter.ai/keys)) | *(none — required for `propose_truth`)* |
+| `OPENROUTER_API_KEY` | Server | API key for Trust Gate LLM reviews via [OpenRouter](https://openrouter.ai/keys) | *(none — required for `propose_truth`)* |
+
+**LLM Provider:** FAVA Trails uses [any-llm-sdk](https://github.com/marekstephens/any-llm-sdk) for unified LLM access. OpenRouter is the default provider (recommended for simplicity — single API key, 100+ models). Additional providers (Anthropic, OpenAI, Bedrock, etc.) can be configured in `config.yaml` for future versions.
 
 The server reads `$FAVA_TRAILS_DATA_REPO/config.yaml` for global settings. Minimal `config.yaml`:
 

codev/resources/arch.md

@@ -4,8 +4,12 @@
 
 ### Provider Routing
 
-All LLM API calls route via **OpenRouter** using `any-llm-sdk`. The `provider="openrouter"`
-argument is passed explicitly to every `acompletion()` call. There is no direct-API path.
+All LLM API calls route via **OpenRouter** (default provider) using `any-llm-sdk`. The `provider="openrouter"`
+argument is passed explicitly to every `acompletion()` call.
+
+**Multi-provider support:** any-llm-sdk enables support for additional providers (Anthropic, OpenAI, Bedrock, etc.).
+The current implementation hardcodes `provider="openrouter"`, but future versions will support provider selection
+via `config.yaml` to enable switching between providers. There is currently no direct-API path.
 
 ```python
 response = await any_llm.acompletion(
@@ -57,5 +61,8 @@ client_args={"timeout": timeout}  # default: 60.0 seconds
 
 ## Configuration (`src/fava_trails/models.py`)
 
-`GlobalConfig` has a single `openrouter_api_key_env` field (default: `"OPENROUTER_API_KEY"`).
+`GlobalConfig` has a single `openrouter_api_key_env` field (default: `"OPENROUTER_API_KEY"`) for OpenRouter API key configuration.
+
+**Future extensibility:** To support additional LLM providers, a `llm_provider` field and provider-specific configuration will be added to `GlobalConfig`. This will enable runtime provider selection via `config.yaml` while maintaining backward compatibility with existing OpenRouter setups.
+
 The previous `openai_api_key_env` field was removed in Spec 17.