feat: Free Models page with provider logos and public API (#1608)

* feat: add Free Models page with provider logos and public API endpoint

- Add Free Models page syncing provider data from awesome-free-llm-apis
  GitHub repo (daily cron at midnight + on startup)
- Add provider logos for all 15 free providers (SVG icons with dark mode variants)
- Add CUSTOM_PROVIDER_LOGOS map in ProviderIcon.tsx for icon resolution
  across Routing, Overview, and Messages pages
- Add public endpoint GET /api/v1/public/free-providers (no auth required)
- Connect button links to built-in provider modal for known providers
  (Gemini, Mistral, OpenRouter, Z AI, Ollama Cloud)
- Ollama Cloud connect button disabled in cloud mode with tooltip
- Rename "Z AI (Zhipu AI)" display name to "Z AI"

* test: improve FreeModels coverage to 100% lines

- Add test for dark mode logo variants
- Add test for disabled Ollama Cloud button in cloud mode
- Add test for built-in provider connect links
- Add test for show models toggle on providers without base_url

Author: SebConejo

.changeset/loose-ducks-happen.md

@@ -0,0 +1,2 @@
+---
+---

.gitignore

@@ -26,3 +26,5 @@ coverage/
 .windsurf/
 /backend/
 .gstack/
+scripts/.env.verify
+scripts/verify-free-model-ids.sh

packages/backend/src/app.module.ts

@@ -24,6 +24,7 @@ import { SseModule } from './sse/sse.module';
 import { GithubModule } from './github/github.module';
 import { PublicStatsModule } from './public-stats/public-stats.module';
 import { SetupModule } from './setup/setup.module';
+import { FreeModelsModule } from './free-models/free-models.module';
 
 const frontendPath = resolveFrontendDir();
 const ONE_YEAR_S = 365 * 24 * 60 * 60;
@@ -72,6 +73,7 @@ const serveStaticImports = frontendPath
     GithubModule,
     PublicStatsModule,
     SetupModule,
+    FreeModelsModule,
   ],
   providers: [
     { provide: APP_GUARD, useClass: SessionGuard },

packages/backend/src/common/constants/cache.constants.ts

@@ -2,3 +2,4 @@ export const DASHBOARD_CACHE_TTL_MS = 30_000;
 export const AGENT_LIST_CACHE_TTL_MS = 60_000;
 export const MODEL_PRICES_CACHE_TTL_MS = 300_000;
 export const PUBLIC_STATS_CACHE_TTL_MS = 86_400_000;
+export const FREE_MODELS_CACHE_TTL_MS = 3_600_000;

packages/backend/src/free-models/free-models-provider-metadata.ts

@@ -0,0 +1,96 @@
+export interface ProviderMetadata {
+  /** Path to self-hosted icon, e.g. '/icons/cohere.svg' */
+  logo: string;
+  /** Override the display name from GitHub data.json */
+  displayName?: string;
+  /** Bullet-point tags shown under the provider name */
+  tags: string[];
+  /** Yellow warning banner text */
+  warning: string;
+}
+
+/**
+ * UI-specific metadata keyed by the exact `name` from GitHub data.json.
+ * baseUrl and model IDs come from GitHub — this map only holds
+ * display/UX fields that don't belong in the shared data source.
+ */
+export const PROVIDER_METADATA: Readonly<Record<string, ProviderMetadata>> = {
+  Cerebras: {
+    logo: '/icons/cerebras.svg',
+    tags: ['Fast inference', 'No credit card required'],
+    warning: '',
+  },
+  'Cloudflare Workers AI': {
+    logo: '/icons/workersai.svg',
+    tags: ['10,000 neurons/day free', 'No credit card required'],
+    warning: '',
+  },
+  Cohere: {
+    logo: '/icons/cohere.svg',
+    tags: ['Up to 1,000 calls/month', 'No credit card required'],
+    warning:
+      'Trial keys cannot be used for production or commercial workloads. Data may be used for training.',
+  },
+  'GitHub Models': {
+    logo: '/icons/github.svg',
+    tags: ['Rate-limited free tier', 'No credit card required'],
+    warning: '',
+  },
+  'Google Gemini': {
+    logo: '/icons/gemini.svg',
+    tags: ['250K TPM (Tokens / Minute) shared across models', 'No credit card required'],
+    warning:
+      'Rate limits apply per Google Cloud project, not per API key. On the free tier, prompts and responses may be used to improve Google products.',
+  },
+  Groq: {
+    logo: '/icons/groq.svg',
+    tags: ['Fast inference', 'No credit card required'],
+    warning: '',
+  },
+  'Hugging Face': {
+    logo: '/icons/huggingface.svg',
+    tags: ['Serverless Inference API', 'No credit card required'],
+    warning: '',
+  },
+  'Kilo Code': {
+    logo: '/icons/kilocode.jpg',
+    tags: ['No credit card required'],
+    warning: 'Prompts and outputs are logged on free models to improve provider products.',
+  },
+  'LLM7.io': {
+    logo: '',
+    tags: ['No credit card required'],
+    warning: '',
+  },
+  'Mistral AI': {
+    logo: '/icons/providers/mistral.svg',
+    tags: ['No credit card required'],
+    warning: '',
+  },
+  'NVIDIA NIM': {
+    logo: '/icons/nvidia.svg',
+    tags: ['1,000 free credits', 'No credit card required'],
+    warning: '',
+  },
+  'Ollama Cloud': {
+    logo: '/icons/ollama.svg',
+    tags: ['No credit card required'],
+    warning: '',
+  },
+  OpenRouter: {
+    logo: '/icons/openrouter.svg',
+    tags: ['Free tier models available', 'No credit card required'],
+    warning: '',
+  },
+  SiliconFlow: {
+    logo: '/icons/siliconflow.svg',
+    tags: ['No credit card required'],
+    warning: '',
+  },
+  'Z AI (Zhipu AI)': {
+    logo: '/icons/zai.svg',
+    displayName: 'Z AI',
+    tags: ['No credit card required'],
+    warning: '',
+  },
+};

packages/backend/src/free-models/free-models-sync.service.spec.ts

@@ -0,0 +1,183 @@
+import { FreeModelsSyncService } from './free-models-sync.service';
+
+const GITHUB_RAW_URL =
+  'https://raw.githubusercontent.com/mnfst/awesome-free-llm-apis/main/data.json';
+
+const sampleData = {
+  lastUpdated: '2026-04-17',
+  providers: [
+    {
+      name: 'Cohere',
+      category: 'provider_api',
+      country: 'CA',
+      flag: '\u{1F1E8}\u{1F1E6}',
+      url: 'https://dashboard.cohere.com/api-keys',
+      baseUrl: 'https://api.cohere.ai/compatibility/v1',
+      description: 'Free trial API key.',
+      footnoteRef: null,
+      models: [
+        {
+          id: 'command-a-03-2025',
+          name: 'Command A (111B)',
+          context: '256K',
+          maxOutput: '4K',
+          modality: 'Text',
+          rateLimit: '20 RPM',
+        },
+      ],
+    },
+    {
+      name: 'Google Gemini',
+      category: 'provider_api',
+      country: 'US',
+      flag: '\u{1F1FA}\u{1F1F8}',
+      url: 'https://aistudio.google.com/app/apikey',
+      baseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai/',
+      description: 'Free tier.',
+      footnoteRef: 1,
+      models: [
+        {
+          id: 'gemini-2.5-flash',
+          name: 'Gemini 2.5 Flash',
+          context: '1M',
+          maxOutput: '65K',
+          modality: 'Text + Image',
+          rateLimit: '10 RPM',
+        },
+      ],
+    },
+  ],
+};
+
+let fetchSpy: jest.SpyInstance;
+
+describe('FreeModelsSyncService', () => {
+  let service: FreeModelsSyncService;
+
+  beforeEach(() => {
+    service = new FreeModelsSyncService();
+    fetchSpy = jest.spyOn(global, 'fetch');
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  describe('onModuleInit', () => {
+    it('calls refreshCache on init', async () => {
+      fetchSpy.mockResolvedValue({
+        ok: true,
+        json: async () => sampleData,
+      });
+
+      await service.onModuleInit();
+      expect(fetchSpy).toHaveBeenCalledWith(GITHUB_RAW_URL);
+      expect(service.getAll()).toHaveLength(2);
+    });
+
+    it('does not throw when refreshCache rejects', async () => {
+      jest.spyOn(service, 'refreshCache').mockRejectedValue(new Error('Unexpected'));
+      await service.onModuleInit();
+    });
+  });
+
+  describe('refreshCache', () => {
+    it('populates cache with successful response', async () => {
+      fetchSpy.mockResolvedValue({
+        ok: true,
+        json: async () => sampleData,
+      });
+
+      const count = await service.refreshCache();
+      expect(count).toBe(2);
+      expect(service.getAll()).toHaveLength(2);
+      expect(service.getAll()[0].name).toBe('Cohere');
+      expect(service.getAll()[1].name).toBe('Google Gemini');
+      expect(service.getLastFetchedAt()).toBeInstanceOf(Date);
+    });
+
+    it('returns 0 when API returns non-OK status', async () => {
+      fetchSpy.mockResolvedValue({ ok: false, status: 503 });
+
+      const count = await service.refreshCache();
+      expect(count).toBe(0);
+      expect(service.getAll()).toHaveLength(0);
+    });
+
+    it('returns 0 when fetch throws', async () => {
+      fetchSpy.mockRejectedValue(new Error('Network error'));
+
+      const count = await service.refreshCache();
+      expect(count).toBe(0);
+      expect(service.getAll()).toHaveLength(0);
+    });
+
+    it('returns 0 when providers array is missing', async () => {
+      fetchSpy.mockResolvedValue({
+        ok: true,
+        json: async () => ({ lastUpdated: '2026-04-17' }),
+      });
+
+      const count = await service.refreshCache();
+      expect(count).toBe(0);
+    });
+
+    it('keeps stale cache when fetch fails after previous success', async () => {
+      fetchSpy.mockResolvedValue({
+        ok: true,
+        json: async () => sampleData,
+      });
+      await service.refreshCache();
+      expect(service.getAll()).toHaveLength(2);
+
+      fetchSpy.mockRejectedValue(new Error('Network error'));
+      const count = await service.refreshCache();
+      expect(count).toBe(0);
+      // Stale cache preserved
+      expect(service.getAll()).toHaveLength(2);
+    });
+
+    it('replaces entire cache on successful refresh', async () => {
+      fetchSpy.mockResolvedValue({
+        ok: true,
+        json: async () => sampleData,
+      });
+      await service.refreshCache();
+      expect(service.getAll()).toHaveLength(2);
+
+      fetchSpy.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          lastUpdated: '2026-04-18',
+          providers: [sampleData.providers[0]],
+        }),
+      });
+      await service.refreshCache();
+      expect(service.getAll()).toHaveLength(1);
+    });
+  });
+
+  describe('getAll', () => {
+    it('returns empty array initially', () => {
+      expect(service.getAll()).toEqual([]);
+    });
+  });
+
+  describe('getLastFetchedAt', () => {
+    it('returns null before any refresh', () => {
+      expect(service.getLastFetchedAt()).toBeNull();
+    });
+
+    it('does not update when fetch fails', async () => {
+      fetchSpy.mockRejectedValue(new Error('fail'));
+      await service.refreshCache();
+      expect(service.getLastFetchedAt()).toBeNull();
+    });
+
+    it('does not update when API returns non-OK', async () => {
+      fetchSpy.mockResolvedValue({ ok: false, status: 500 });
+      await service.refreshCache();
+      expect(service.getLastFetchedAt()).toBeNull();
+    });
+  });
+});

packages/backend/src/free-models/free-models-sync.service.ts

@@ -0,0 +1,85 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { Cron, CronExpression } from '@nestjs/schedule';
+
+export interface GitHubModel {
+  id: string | null;
+  name: string;
+  context: string;
+  maxOutput: string;
+  modality: string;
+  rateLimit: string;
+}
+
+export interface GitHubProvider {
+  name: string;
+  category: string;
+  country: string;
+  flag: string;
+  url: string;
+  baseUrl: string | null;
+  description: string;
+  footnoteRef: number | null;
+  models: GitHubModel[];
+}
+
+interface GitHubDataJson {
+  lastUpdated: string;
+  providers: GitHubProvider[];
+}
+
+const GITHUB_RAW_URL =
+  'https://raw.githubusercontent.com/mnfst/awesome-free-llm-apis/main/data.json';
+
+@Injectable()
+export class FreeModelsSyncService implements OnModuleInit {
+  private readonly logger = new Logger(FreeModelsSyncService.name);
+  private cache: GitHubProvider[] = [];
+  private lastFetchedAt: Date | null = null;
+
+  async onModuleInit(): Promise<void> {
+    try {
+      await this.refreshCache();
+    } catch (err) {
+      this.logger.error(`Startup free models sync failed: ${err}`);
+    }
+  }
+
+  @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
+  async refreshCache(): Promise<number> {
+    this.logger.log('Refreshing free models cache from GitHub...');
+    const data = await this.fetchData();
+    if (!data) return 0;
+
+    this.cache = data.providers;
+    this.lastFetchedAt = new Date();
+    this.logger.log(`Free models cache loaded: ${data.providers.length} providers`);
+    return data.providers.length;
+  }
+
+  getAll(): readonly GitHubProvider[] {
+    return this.cache;
+  }
+
+  getLastFetchedAt(): Date | null {
+    return this.lastFetchedAt;
+  }
+
+  private async fetchData(): Promise<GitHubDataJson | null> {
+    try {
+      const res = await fetch(GITHUB_RAW_URL);
+      if (!res.ok) {
+        this.logger.error(`GitHub raw returned ${res.status}`);
+        return null;
+      }
+      const body = (await res.json()) as GitHubDataJson;
+      if (!Array.isArray(body.providers)) {
+        this.logger.error('GitHub data.json missing providers array');
+        return null;
+      }
+      return body;
+    } catch (err) {
+      this.logger.error(`Failed to fetch free models data: ${err}`);
+      return null;
+    }
+  }
+}