Skip to content

Add Fal to Gateway Health Dashboard & Integration Guide#99

Merged
vdimarco merged 2 commits intomainfrom
terragon/add-fal-to-gateway-guide-jiasrv
Oct 31, 2025
Merged

Add Fal to Gateway Health Dashboard & Integration Guide#99
vdimarco merged 2 commits intomainfrom
terragon/add-fal-to-gateway-guide-jiasrv

Conversation

@vdimarco
Copy link
Contributor

@vdimarco vdimarco commented Oct 31, 2025

Summary

  • Integrates Fal.ai into the gateway health dashboard and integration guide.
  • Fal uses a static catalog (no live API endpoint) and now requires a higher minimum model count (50).

Changes

Code

  • check_and_fix_gateway_models.py
    • Import and configure Fal model cache (_fal_models_cache).
    • Add Fal to GATEWAY_CONFIG with:
      • name: Fal.ai
      • url: None (static catalog)
      • api_key_env: FAL_KEY
      • api_key: getattr(Config, 'FAL_KEY', 'static_catalog')
      • cache: _fal_models_cache
      • min_expected_models: 50
      • header_type: bearer

Documentation

  • docs/GATEWAY_INTEGRATION_GUIDE.md
    • Add new section: "Add to Gateway Health Dashboard" detailing:
      • Import Fal cache and register Fal in GATEWAY_CONFIG with the fields above
      • Notes for static catalog: set url to None and use dummy API key 'static_catalog'
      • The dashboard will show cache status even without a live endpoint
    • Update sections to reflect Fal in:
      • System Routes Dashboard
      • Catalog Endpoints references
    • Adjust verification steps to ensure Fal appears on the health dashboard
    • Update the "Key files to review" list to include gateway health/dashboard integration

How to test

  • Start the gateway service and verify Fal appears on the health dashboard at /health/gateways/dashboard (gateway health view).
  • Check the gateway cache status for Fal; it should show cache activity/status even though there is no live endpoint.
  • If you have a static Fal catalog, ensure /catalog/v1/models?gateway=fal returns the Fal models (given the static catalog is populated).
  • Validate there are no key/env errors if FAL_KEY is not provided ( Fal uses 'static_catalog' by default ).

Notes

  • No live API endpoint is required for Fal. This change enables Fal to be tracked and displayed in the health dashboard using a static catalog.
  • This update is isolated to Fal and does not affect existing gateways.

Documentation references

  • Gateway health dashboard URL: /health/gateways/dashboard
  • Catalog API endpoints: /catalog/v1/models?gateway=fal (static catalog)

🌿 Generated by Terry


ℹ️ Tag @terragon-labs to ask questions and address PR feedback

📎 Task: https://www.terragonlabs.com/task/2ca815ef-a1d1-4581-b78d-dc34460d9e1e


Note

Integrates Fal.ai (static catalog) into the gateway health dashboard with url=None and min models 50, updates integration guide, and adapts tests to include Fal and allow None URLs.

  • Gateway Health (check_and_fix_gateway_models.py):
    • Import _fal_models_cache and add fal to GATEWAY_CONFIG (url=None, dummy API key via getattr(Config, 'FAL_KEY', 'static_catalog'), min_expected_models=50, header_type='bearer').
  • Docs (docs/GATEWAY_INTEGRATION_GUIDE.md):
    • Add “Gateway Health Dashboard” integration steps; update system routes, catalog references, verification checklist, and reference files.
    • Add Fal-specific notes for static catalog behavior (no endpoint, dummy key, min models 50).
  • Tests (tests/health/test_gateway_health.py):
    • Include fal in required gateways and allow url to be None for static catalogs.

Written by Cursor Bugbot for commit 3ac9bc3. This will update automatically on new commits. Configure here.

- Imported _fal_models_cache to caching system
- Added Fal.ai entry in GATEWAY_CONFIG with static catalog settings
- Updated documentation for adding gateways to dashboard and health checks
- Set Fal.ai url to None to indicate static catalog with dummy API key
- Increased min_expected_models to 50 for Fal.ai
- Enhanced integration guide to include gateway health dashboard updates

Co-authored-by: terragon-labs[bot] <terragon-labs[bot]@users.noreply.github.com>
@vercel
Copy link

vercel bot commented Oct 31, 2025

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Comments Updated (UTC)
gatewayz-app Ready Ready Preview Comment Oct 31, 2025 3:54am
gatewayz-backend Ready Ready Preview Comment Oct 31, 2025 3:54am

@openhands-ai
Copy link

openhands-ai bot commented Oct 31, 2025

Looks like there are a few issues preventing this PR from being merged!

  • GitHub Actions are failing:
    • Run Tests
    • CI Pipeline

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #99 at branch `terragon/add-fal-to-gateway-guide-jiasrv`

Feel free to include any additional details that might help me get this PR into a better state.

You can manage your notification settings

- Added 'fal' to the list of expected gateways in the health checker tests.
- Updated URL validation to permit None values for gateways with static catalogs like Fal, ensuring tests accept URLs that are either strings starting with http(s) or None.

Co-authored-by: terragon-labs[bot] <terragon-labs[bot]@users.noreply.github.com>
@vdimarco vdimarco merged commit 829cfb8 into main Oct 31, 2025
18 checks passed
Armin2708 pushed a commit that referenced this pull request Nov 26, 2025
* feat(gateway): add Fal.ai gateway to health dashboard configuration

- Imported _fal_models_cache to caching system
- Added Fal.ai entry in GATEWAY_CONFIG with static catalog settings
- Updated documentation for adding gateways to dashboard and health checks
- Set Fal.ai url to None to indicate static catalog with dummy API key
- Increased min_expected_models to 50 for Fal.ai
- Enhanced integration guide to include gateway health dashboard updates

Co-authored-by: terragon-labs[bot] <terragon-labs[bot]@users.noreply.github.com>

* test(health): add 'fal' gateway and allow None URLs in health checks

- Added 'fal' to the list of expected gateways in the health checker tests.
- Updated URL validation to permit None values for gateways with static catalogs like Fal, ensuring tests accept URLs that are either strings starting with http(s) or None.

Co-authored-by: terragon-labs[bot] <terragon-labs[bot]@users.noreply.github.com>

---------

Co-authored-by: terragon-labs[bot] <terragon-labs[bot]@users.noreply.github.com>
vdimarco added a commit that referenced this pull request Feb 1, 2026
… instead of dropped model_id column

Fixes #99 Sentry errors with 'column models.model_id does not exist'

## Issues Fixed

**Sentry Issues**: 99 unresolved errors in last 24 hours
**Error**: Database pricing lookup failed for [model]: {'code': '42703', 'details': None, 'hint': None, 'message': 'column models.model_id does not exist'}

## Root Cause

Migration `20260131000002_drop_model_id_column.sql` dropped the redundant `model_id` column from the `models` table in favor of `model_name`. However, several database query functions were still attempting to query the `models` table using the now-nonexistent `model_id` column:

1. `src/services/pricing_lookup.py:_get_pricing_from_database()` - Line 229
2. `src/services/pricing.py:get_model_pricing_from_db()` - Line 74
3. `src/db/failover_db.py:get_providers_for_model()` - Lines 65, 94
4. `src/db/failover_db.py:get_provider_model_id()` - Line 209

Additionally, `failover_db.py` was still selecting pricing columns directly from the `models` table instead of using the `model_pricing` relationship.

## Solution

### 1. Updated pricing_lookup.py
- Changed query from `.eq("model_id", model_id)` to `.eq("model_name", model_id)`
- Updated SELECT clause to use `model_name` instead of `model_id`
- Added clarifying comments about the migration

### 2. Updated pricing.py
- Changed query from `.eq("model_id", candidate)` to `.eq("model_name", candidate)`
- Updated SELECT clause to use `model_name` instead of `model_id`
- Added clarifying comments about the migration

### 3. Updated failover_db.py
- **Query Changes:**
  - Changed filter from `.eq("model_id", model_id)` to `.eq("model_name", model_id)`
  - Updated SELECT clause to use `model_name` instead of `model_id`
  - Removed direct pricing column selects (pricing_prompt, pricing_completion, etc.)
  - Added `model_pricing` relationship join to get pricing data

- **Data Processing Changes:**
  - Updated to extract pricing from `model_pricing` relationship
  - Changed field mapping from `row["model_id"]` to `row["model_name"]`
  - Added extraction of pricing from nested `model_pricing` object
  - Updated `get_provider_model_id()` to use `model_name` filter

## Changes Made

### Modified Files
1. `src/services/pricing_lookup.py` - Updated database query to use model_name
2. `src/services/pricing.py` - Updated database query to use model_name
3. `src/db/failover_db.py` - Updated queries and data extraction for model_name and model_pricing table

### New Test Files
1. `tests/services/test_pricing_lookup_model_name_fix.py` - 7 comprehensive tests
2. `tests/db/test_failover_db_model_name_fix.py` - 6 comprehensive tests
3. `tests/services/test_pricing_model_name_fix.py` - 7 comprehensive tests

**Total**: 20 new tests covering:
- Query structure verification (uses model_name, not model_id)
- Pricing extraction from model_pricing table
- Missing data handling
- Error handling
- Per-token to per-1M conversion
- Multiple candidate ID handling

## Testing

### Unit Tests
- ✅ 20 new tests added covering all modified functions
- ✅ Tests verify queries use model_name instead of model_id
- ✅ Tests verify pricing extracted from model_pricing relationship
- ✅ Tests verify error handling and edge cases

### Migration Compatibility
- ✅ Aligns with migration `20260131000002_drop_model_id_column.sql`
- ✅ Compatible with new schema: model_name (canonical) + provider_model_id (provider-specific)
- ✅ Uses model_pricing table for pricing data (per-token format)

## Impact

### Before Fix
- 🔴 99 Sentry errors in last 24 hours
- 🔴 Database queries failing with PostgreSQL error 42703
- 🔴 Pricing lookups failing for all providers
- 🔴 Failover queries unable to find provider alternatives

### After Fix
- ✅ All database queries use correct column (model_name)
- ✅ Pricing lookups work correctly from model_pricing table
- ✅ Failover system can find provider alternatives
- ✅ No more column does not exist errors

## Database Schema Reference

After migration `20260131000002`, the models table schema is:

| Field | Type | Purpose |
|-------|------|---------|
| `id` | `int` | Primary key |
| `model_name` | `str` | Canonical identifier (NEW PRIMARY IDENTIFIER) |
| `provider_model_id` | `str` | Provider-specific API identifier |
| ~~`model_id`~~ | ~~`str`~~ | ❌ REMOVED (redundant) |

The `model_pricing` table uses `model_id` as a foreign key to `models.id` (the integer primary key).

## Related
- Migration: `supabase/migrations/20260131000002_drop_model_id_column.sql`
- Documentation: `docs/MODEL_ID_MIGRATION_SUMMARY.md`
- Issue: GATEWAYZ-BACKEND-86 (99 errors)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant