[ENHANCE] Standardize LLM Provider Setup: Model ID Prefixes & Configuration Guards

[lele-maxwell]

Problem

Currently, setting up OpenFlows with different LLM providers (especially transitioning between Fireworks and OpenAI/Proxy) is error-prone due to differences in how model IDs are resolved.

Specific pain points:

1. Prefix Dependency: Fireworks requires accounts/fireworks/models/ prefixes, while OpenAI-compatible endpoints typically expect raw model names (e.g., gpt-4o).
2. Implicit Fallbacks: If a provider key (like FIREWORKS_API_KEY) is missing, the system silently falls back to the next provider but carries over the model ID from the registry. This leads to 400 Bad Request: invalid model ID errors on the fallback provider because the prefix is invalid there.
3. Documentation Gap: Current setup guides do not emphasize that registry.json model IDs must match the specific identifier format of the active OPENAI_BASE_URL or provider.

Proposed Improvements

1. Documentation Overhaul

• Dedicated Provider Guide: Create docs/providers.md with clear examples for each backend.
  • Fireworks: Show the account-prefixed format.
  • OpenAI/Gateway: Show the raw name format.
• Troubleshooting Case Study: Document the 400 Bad Request error specifically as a "Model ID / Provider Mismatch".

2. Code-Side Resilience (future)

• Automatic Prefix Stripping: Update the OpenAI client to detect and handle Fireworks-specific model ID prefixes when hitting standard OpenAI endpoints.
• Configuration Validation: Add a startup check that validates if the model IDs in the agent registry are compatible with the primary configured provider.

3. Registry Defaults

• Update the default agent registry template or .env.example to clearly state the model format requirements.

Example Scenario

A user has FIREWORKS_API_KEY disabled and OPENAI_API_KEY enabled. They set model_backend to accounts/fireworks/models/gpt-4o. The request fails at OpenAI with a 400 error because OpenAI doesn't recognize the Fireworks-specific account path.
so in this case the correct set is "model_backend": "gpt-4o",