Merge pull request #14 from calesthio/codex/fix-fal-provider-bias

Remove fal-first provider guidance
2026-08-05 15:20:40 +08:00 · 2026-04-08 13:06:29 -07:00
parent dfae315656 a919fde450
commit e815126f5a
9 changed files with 34 additions and 26 deletions
--- a/.agents/skills/ai-video-gen/SKILL.md
+++ b/.agents/skills/ai-video-gen/SKILL.md
@@ -9,7 +9,6 @@ metadata:
      env_any:
        - HEYGEN_API_KEY
        - FAL_KEY
-    primaryEnv: FAL_KEY
 ---

 # Video Generation (Multi-Gateway)
@@ -25,9 +24,12 @@ Generate AI videos from text prompts. Supports multiple providers via two API ga

 ## Authentication

-**fal.ai (recommended primary):** Set `FAL_KEY` environment variable. Get a key at https://fal.ai/dashboard/keys
+Use whichever configured gateway best matches the user's available providers and cost/quality goals.

-**HeyGen (secondary):** Set `HEYGEN_API_KEY` environment variable.
+- **HeyGen:** Set `HEYGEN_API_KEY` to access the multi-model gateway.
+- **fal.ai:** Set `FAL_KEY` to access Kling, MiniMax, and Veo through fal.ai.
+
+Do not describe either gateway as the default or top choice without checking the registry and current task fit first.

 ```bash
 curl -X POST "https://api.heygen.com/v1/workflows/executions" \
--- a/.claude/skills/ai-video-gen/SKILL.md
+++ b/.claude/skills/ai-video-gen/SKILL.md
@@ -9,7 +9,6 @@ metadata:
      env_any:
        - HEYGEN_API_KEY
        - FAL_KEY
-    primaryEnv: FAL_KEY
 ---

 # Video Generation (Multi-Gateway)
@@ -25,9 +24,12 @@ Generate AI videos from text prompts. Supports multiple providers via two API ga

 ## Authentication

-**fal.ai (recommended primary):** Set `FAL_KEY` environment variable. Get a key at https://fal.ai/dashboard/keys
+Use whichever configured gateway best matches the user's available providers and cost/quality goals.

-**HeyGen (secondary):** Set `HEYGEN_API_KEY` environment variable.
+- **HeyGen:** Set `HEYGEN_API_KEY` to access the multi-model gateway.
+- **fal.ai:** Set `FAL_KEY` to access Kling, MiniMax, and Veo through fal.ai.
+
+Do not describe either gateway as the default or top choice without checking the registry and current task fit first.

 ```bash
 curl -X POST "https://api.heygen.com/v1/workflows/executions" \
--- a/.env.example
+++ b/.env.example
@@ -1,7 +1,7 @@
 # OpenMontage - Environment Variables
 # Copy this to .env and fill in your keys

-# --- fal.ai (one key unlocks the most tools) ---
+# --- Image + video gateway ---
 FAL_KEY=                     # FLUX images, Google Veo video, Kling video, MiniMax video, Recraft images
                             # Get one at https://fal.ai/dashboard/keys

--- a/README.md
+++ b/README.md
@@ -145,7 +145,7 @@ This repo is built for agentic operation. If you're an OpenClaw-style agent, her
 ```bash
 # .env — every key is optional, add what you have

-# Best bang for buck — one key unlocks 5 tools:
+# Image + video gateway:
 FAL_KEY=your-key               # FLUX images + Google Veo, Kling, MiniMax video + Recraft images

 # Free stock media:
@@ -217,7 +217,7 @@ Copy any of these into your AI coding assistant after setup. Each one runs a ful

 > "Make a data-driven explainer about coffee consumption around the world"

-### With FAL_KEY (~$0.15–$1.50)
+### With an image/video provider configured (~$0.15–$1.50)

 > "Create a 30-second Ghibli-style animated video of a magical floating library in the clouds at golden hour"

--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -140,13 +140,13 @@ Key queries:

 Three selector tools abstract multi-provider capabilities:

-| Selector | Capability | Providers (priority order) |
-|----------|-----------|---------------------------|
-| `tts_selector` | Text-to-speech | ElevenLabs > Google TTS > OpenAI > Piper (offline) |
-| `image_selector` | Image generation | FLUX > Grok > Google Imagen > DALL-E > Recraft > LocalDiffusion > Pexels/Pixabay (stock) |
-| `video_selector` | Video generation | Grok > Kling > Runway > VEO > MiniMax > HeyGen > LTX (modal) > LTX (local) > CogVideo > Hunyuan > WAN > Pexels/Pixabay (stock) |
+| Selector | Capability | How selection works |
+|----------|-----------|---------------------|
+| `tts_selector` | Text-to-speech | Ranks discovered providers by task fit, quality, control, reliability, cost, latency, and continuity |
+| `image_selector` | Image generation | Ranks discovered providers from the live registry; no hardcoded provider order |
+| `video_selector` | Video generation | Ranks discovered providers from the live registry; user preference is respected when explicitly provided |

-Selectors route based on: user preference > availability > fallback order. They adapt input schemas between providers transparently.
+Selectors route based on: user preference when explicitly set, then scored ranking across available providers. They adapt input schemas between providers transparently.

 ### Tool Inventory by Category

--- a/docs/PROVIDERS.md
+++ b/docs/PROVIDERS.md
@@ -14,7 +14,7 @@ Everything you need to know about every provider in OpenMontage — setup instru
 | 2 | **$0** | Google API key | TTS with 700+ voices (1M chars/month free) + $300 new account credit |
 | 3 | **$0** | ElevenLabs | Premium TTS + music + SFX (10K chars/month free) |
 | 4 | **$0** | Piper (local install) | Fully offline TTS — no API key, no cost, no network |
-| 5 | **~$0.03/image** | fal.ai | FLUX images + Kling/Veo/MiniMax video + Recraft — one key unlocks 6 tools |
+| 5 | **~$0.03/image** | fal.ai | FLUX images + Kling/Veo/MiniMax video + Recraft — broad single-key image + video coverage |
 | 6 | **~$0.04/image** | OpenAI | DALL-E 3 images + OpenAI TTS |
 | 7 | **~$0.04/image** | Google Imagen | Imagen 4 images (shares the Google API key) |
 | 8 | **$12/month** | Runway | Gen-4 video — highest quality AI video |
@@ -94,7 +94,7 @@ OpenMontage now uses those published rates in the Grok tool estimators.

 ### fal.ai — Multi-Model Gateway

-> **Best bang for buck.** One API key unlocks 6 tools across image and video generation.
+> **Broad single-key coverage.** One API key unlocks image and video providers across multiple models.

 **Tools unlocked:** `flux_image`, `recraft_image`, `kling_video`, `veo_video`, `minimax_video`
 **Env var:** `FAL_KEY`
@@ -678,8 +678,8 @@ A: FFmpeg + Node.js (both free, local). FFmpeg handles video assembly, audio mix
 **Q: I don't have any video generation providers. Can I still make videos?**
 A: Yes. The agent generates still images (via any image provider — even free stock from Pexels/Pixabay) and Remotion composes them into animated video with spring physics transitions, text cards, stat cards, and charts. This is the default path for explainer and animation pipelines when no video gen is configured.

-**Q: What's the cheapest way to get AI-generated images and video?**
-A: fal.ai (`FAL_KEY`). One key unlocks FLUX images at ~$0.03/image and multiple video providers. No subscription — pay only for what you generate.
+**Q: What's one low-friction way to get AI-generated images and video?**
+A: fal.ai (`FAL_KEY`) is one pay-as-you-go option with broad single-key coverage. It unlocks FLUX images plus multiple video providers. No subscription — pay only for what you generate.

 **Q: I have a GPU. What can I run locally for free?**
 A: Set `VIDEO_GEN_LOCAL_ENABLED=true` and install `diffusers`. You get WAN 2.1, Hunyuan, CogVideo, and LTX video generation plus Stable Diffusion image generation — all free, all offline.
--- a/skills/meta/onboarding.md
+++ b/skills/meta/onboarding.md
@@ -41,7 +41,7 @@ Based on discovery, classify the setup:
 | Tier | What's Available | Best Pipelines |
 |------|-----------------|----------------|
 | **Zero-key** | Piper TTS + Pexels/Pixabay stock (if keys added) + Remotion + FFmpeg | Animated Explainer (stock visuals + free narration) |
-| **Starter** | One image gen provider (e.g., FLUX via FAL_KEY) + free TTS + Remotion | Animated Explainer, Animation (AI-generated visuals) |
+| **Starter** | One configured image generation provider + free TTS + Remotion | Animated Explainer, Animation (AI-generated visuals) |
 | **Standard** | Image gen + TTS + music gen | Animated Explainer, Animation, Screen Demo, Hybrid |
 | **Full** | Video gen + image gen + premium TTS + music | All pipelines including Cinematic, Avatar, Talking Head |
 | **Full + GPU** | Cloud APIs + local video gen models | All pipelines with free local fallbacks |
@@ -61,7 +61,7 @@ Present a **short, friendly capability summary**. Do NOT dump the raw provider m

 **Available pipelines:** [List the pipelines that work with their setup, with one-line descriptions]

-**Quick upgrades:** [If applicable — "Add `FAL_KEY` to your `.env` to unlock AI-generated images (FLUX) and video (Veo, Kling, MiniMax) — one key, five tools."]
+**Quick upgrades:** [If applicable — summarize the best 1-2 unlocks from `provider_menu()` based on the user's missing capabilities and actual install instructions. Do not hardcode `FAL_KEY` or any provider as the default suggestion.]

 ---

@@ -89,7 +89,7 @@ Based on the user's tier, present **3 ready-to-use prompts** they can copy right

 > **Try this:** "Create an animated explainer about how CRISPR gene editing works, with AI-generated visuals"
 >
-> I'll use FLUX to generate custom images for each scene — much more visually striking than stock.
+> I'll use your configured image generator to create custom visuals for each scene — much more visually striking than stock.

 > **Also try:** "Make a short documentary-style video about urban beekeeping — keep it grounded and textural, not flashy" *(Hybrid pipeline — source + generated support)*

@@ -137,7 +137,7 @@ Common questions and how to respond:

 **"What does it cost?"**
 - Zero-key path: $0
- With FAL_KEY: typically $0.30–$1.50 per video depending on image count
+- With one paid image/video provider configured: typically $0.30–$1.50 per video depending on asset count
 - Full setup: $1–$3 for most videos
 - Always: "I'll show you exact cost estimates before spending anything."

--- a/skills/meta/video-reference-analyst.md
+++ b/skills/meta/video-reference-analyst.md
@@ -116,8 +116,8 @@ Be honest about gaps. If video generation is needed but unavailable, say so clea
 "This reference uses generated sci-fi footage. Right now you don't have any video
 generation providers configured. Here are your options:

-• Add FAL_KEY to .env → unlocks Kling 3.0, MiniMax, Wan (best for cinematic/sci-fi)
-• Add REPLICATE_API_TOKEN → unlocks LTX Video (good for short clips)
+• Add the gateway or provider key recommended by `provider_menu()` for video generation
+• If multiple provider options are available, summarize the tradeoffs and recommend one based on the user's brief
 • Proceed without video gen → I'll use stock footage + Remotion animations instead
  (different feel, but still works)

@@ -125,7 +125,7 @@ Which would you prefer?"
 ```

 Read install_instructions from the registry for each unavailable tool — do NOT
-hardcode key names or setup URLs.
+hardcode key names, provider names, or setup URLs.

 ### Step 3: Ask Critical Questions

--- a/tools/tool_registry.py
+++ b/tools/tool_registry.py
@@ -242,6 +242,10 @@ class ToolRegistry:
                menu[cap]["unavailable"].append(entry)
            menu[cap]["total"] += 1

+        for bucket in menu.values():
+            bucket["available"].sort(key=lambda entry: (entry["provider"], entry["name"]))
+            bucket["unavailable"].sort(key=lambda entry: (entry["provider"], entry["name"]))
+
        return dict(sorted(menu.items()))

    def gpu_required_tools(self) -> list[str]: