7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
feat: add AI Horde provider (#345)
Tashfeen1fdcae46d035
diff --git a/README.md b/README.mdindex c1c1131d..2c7cb583 100644--- a/README.md+++ b/README.md@@ -74,7 +74,7 @@ The problem is that stacking them by hand is painful: seventeen different SDKs,</tr><tr><td align="center"><a href="https://endpoints.ai.cloud.ovh.net"><b>OVH AI Endpoints</b><br/>Qwen3.5 397B · GPT-OSS · Llama 3.3 (anon ok)</a></td>-<td align="center"></td>+<td align="center"><a href="https://aihorde.net"><b>AI Horde</b><br/>Community Llama · Gemma · Cydonia (anon ok, slow)</a></td><td align="center"></td><td align="center"></td></tr>@@ -711,6 +711,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full migration CLI and workflow<a href="https://github.com/allababbot"><img src="https://images.weserv.nl/?url=github.com/allababbot.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@allababbot" /></a><a href="https://github.com/johan-droid"><img src="https://images.weserv.nl/?url=github.com/johan-droid.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@johan-droid" /></a><a href="https://github.com/redenfire"><img src="https://images.weserv.nl/?url=github.com/redenfire.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@redenfire" /></a>+<a href="https://github.com/itzpingcat"><img src="https://images.weserv.nl/?url=github.com/itzpingcat.png&w=60&h=60&fit=cover&mask=circle" width="60" alt="@itzpingcat" /></a>## Terms of Service review@@ -731,6 +732,7 @@ A self-hosted, single-user, personal-use setup was re-reviewed against each prov| Z.ai (api.z.ai) | ⚠️ Caution | New row — Singapore entity (distinct from Zhipu CN). §III.3(l) anti-traffic-redirect clause could plausibly be read against a proxy; no explicit personal-use carve-out. || Ollama Cloud | ✅ Likely OK | New row — Free plan permits cloud-model access (1 concurrent, 5-hour session caps). No anti-proxy / anti-resale clauses found. *(Integration tracked in #14.)* || OVH AI Endpoints | ✅ Likely OK | New row (June 2026) — anonymous access is officially documented (2 req/min per IP per model). OVH reserves the right to introduce token/consumption caps. |+| AI Horde | ✅ Likely OK | New row (June 2026) — a free, community-powered commons run by the Haidra non-profit; anonymous use is officially supported (key `0000000000`, lowest queue priority). No anti-proxy / anti-resale clause. The OpenAI proxy is a pilot and may be restricted by usage. *(Integration #345.)* |Rules of thumb that keep most providers happy: **one account per provider**, **no reselling**, **no sharing your endpoint with other humans**, **don't hammer a free tier as a paid production backend**. This is informational, not legal advice — read each provider's ToS and make your own call.diff --git a/client/src/pages/FallbackPage.tsx b/client/src/pages/FallbackPage.tsxindex 5ba80c73..1d9398de 100644--- a/client/src/pages/FallbackPage.tsx+++ b/client/src/pages/FallbackPage.tsx@@ -300,6 +300,7 @@ const platformColors: Record<string, string> = {routeway: '#14b8a6',bazaarlink: '#e11d48',ainative: '#22c55e',+ aihorde: '#dc2626',}// A 0..1 value as a thin horizontal bar with the number beside it.diff --git a/client/src/pages/KeysPage.tsx b/client/src/pages/KeysPage.tsxindex e60c009c..48e44457 100644--- a/client/src/pages/KeysPage.tsx+++ b/client/src/pages/KeysPage.tsx@@ -73,6 +73,7 @@ const PLATFORMS: { value: Platform; label: string; url: string; keyless?: boolea{ value: 'routeway', label: 'Routeway (free key)', url: 'https://routeway.ai' },{ value: 'bazaarlink', label: 'BazaarLink (free key)', url: 'https://bazaarlink.ai' },{ value: 'ainative', label: 'AINative Studio (free key)', url: 'https://ainative.studio' },+ { value: 'aihorde', label: 'AI Horde (no key needed, slow)', url: 'https://aihorde.net/register', keyless: true },]// 'custom' is configured through its own form (base URL + model), not thediff --git a/server/src/__tests__/providers/aihorde.test.ts b/server/src/__tests__/providers/aihorde.test.tsnew file mode 100644index 00000000..8bb9643b--- /dev/null+++ b/server/src/__tests__/providers/aihorde.test.ts@@ -0,0 +1,129 @@+import { describe, it, expect, vi, beforeEach } from 'vitest';+import { AIHordeProvider } from '../../providers/aihorde.js';++// AI Horde's OpenAI proxy diverges from the OpenAI contract; these tests pin the+// AIHordeProvider normalizations that keep it from 422-ing or recording zero+// usage. See issue #345.+describe('AIHordeProvider', () => {+ let provider: AIHordeProvider;++ beforeEach(() => {+ provider = new AIHordeProvider();+ });++ /** Mock the upstream proxy: capture the outgoing request, return an+ * OpenAI-shaped body with AI Horde's kudos-only usage. */+ function mockProxy(content = 'PONG') {+ const captured: { url: string; init: any; body: any } = { url: '', init: null, body: null };+ vi.spyOn(global, 'fetch').mockImplementationOnce(async (url, init) => {+ captured.url = String(url);+ captured.init = init;+ captured.body = JSON.parse((init as any).body);+ return {+ ok: true,+ status: 200,+ json: () => Promise.resolve({+ id: 'horde-1',+ object: 'chat.completion',+ created: 111,+ model: 'aphrodite/TheDrummer/Skyfall-31B-v4.2',+ choices: [{ index: 0, message: { role: 'assistant', content }, finish_reason: 'stop' }],+ usage: { kudos: 2 }, // AI Horde returns kudos, not token counts+ }),+ headers: { get: () => null },+ } as any;+ });+ return captured;+ }++ it('has correct platform/name and is keyless', () => {+ expect(provider.platform).toBe('aihorde');+ expect(provider.name).toBe('AI Horde');+ expect(provider.keyless).toBe(true);+ });++ it('floors max_tokens to 16 and wraps a string stop in an array', async () => {+ const cap = mockProxy();+ await provider.chatCompletion('no-key', [{ role: 'user', content: 'hi' }], 'm', {+ max_tokens: 4,+ stop: 'END',+ });+ expect(cap.body.max_tokens).toBe(16);+ expect(cap.body.stop).toEqual(['END']);+ });++ it('defaults max_tokens when the caller omits it', async () => {+ const cap = mockProxy();+ await provider.chatCompletion('no-key', [{ role: 'user', content: 'hi' }], 'm');+ expect(cap.body.max_tokens).toBeGreaterThanOrEqual(16);+ });++ it('passes an array stop through unchanged', async () => {+ const cap = mockProxy();+ await provider.chatCompletion('no-key', [{ role: 'user', content: 'hi' }], 'm', {+ stop: ['A', 'B'],+ });+ expect(cap.body.stop).toEqual(['A', 'B']);+ });++ it('drops tools/tool_choice/parallel_tool_calls (no tool support)', async () => {+ const cap = mockProxy();+ await provider.chatCompletion('no-key', [{ role: 'user', content: 'hi' }], 'm', {+ tools: [{ type: 'function', function: { name: 'f', parameters: { type: 'object', properties: {} } } }],+ tool_choice: 'auto',+ parallel_tool_calls: true,+ });+ expect(cap.body.tools).toBeUndefined();+ expect(cap.body.tool_choice).toBeUndefined();+ expect(cap.body.parallel_tool_calls).toBeUndefined();+ });++ it('maps the keyless sentinel to the anonymous key, and forwards a real key', async () => {+ const anon = mockProxy();+ await provider.chatCompletion('no-key', [{ role: 'user', content: 'hi' }], 'm');+ expect(anon.init.headers.Authorization).toBe('Bearer 0000000000');++ const real = mockProxy();+ await provider.chatCompletion('MY-REAL-HORDE-KEY', [{ role: 'user', content: 'hi' }], 'm');+ expect(real.init.headers.Authorization).toBe('Bearer MY-REAL-HORDE-KEY');+ });++ it('synthesizes token usage when the proxy returns kudos', async () => {+ mockProxy('PONG'); // 4 chars -> ceil(4/4)=1 completion token+ const result = await provider.chatCompletion(+ 'no-key',+ [{ role: 'user', content: 'Reply with exactly one word: PONG' }], // 33 chars -> 9+ 'm',+ );+ expect(result.usage.prompt_tokens).toBe(9);+ expect(result.usage.completion_tokens).toBe(1);+ expect(result.usage.total_tokens).toBe(10);+ expect((result.usage as any).kudos).toBeUndefined();+ expect(result._routed_via?.platform).toBe('aihorde');+ });++ it('streams the queued generation as a single content delta', async () => {+ mockProxy('hello world');+ const chunks: string[] = [];+ let finish: string | null = null;+ for await (const c of provider.streamChatCompletion('no-key', [{ role: 'user', content: 'hi' }], 'm')) {+ if (c.choices[0].delta.content) chunks.push(c.choices[0].delta.content);+ if (c.choices[0].finish_reason) finish = c.choices[0].finish_reason;+ }+ expect(chunks.join('')).toBe('hello world');+ expect(finish).toBe('stop');+ });++ it('surfaces AI Horde\'s {detail} error shape', async () => {+ vi.spyOn(global, 'fetch').mockImplementationOnce(async () => ({+ ok: false,+ status: 406,+ statusText: 'Not Acceptable',+ json: () => Promise.resolve({ detail: 'Error: No user matching sent API Key.' }),+ headers: { get: () => null },+ } as any));+ await expect(+ provider.chatCompletion('bad', [{ role: 'user', content: 'hi' }], 'm'),+ ).rejects.toThrow('No user matching sent API Key');+ });+});diff --git a/server/src/providers/aihorde.ts b/server/src/providers/aihorde.tsnew file mode 100644index 00000000..8b22aff7--- /dev/null+++ b/server/src/providers/aihorde.ts@@ -0,0 +1,212 @@+import type {+ ChatMessage,+ ChatContent,+ ChatCompletionResponse,+ ChatCompletionChunk,+ Platform,+} from '@freellmapi/shared/types.js';+import { BaseProvider, providerHttpError, type CompletionOptions } from './base.js';+import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';++/**+ * AI Horde — free, community-powered inference served by volunteer workers and+ * exposed through an OpenAI-compatible proxy at https://oai.aihorde.net/v1+ * (issue #345).+ *+ * It is deliberately NOT a plain OpenAICompatProvider: the proxy diverges from+ * the OpenAI contract in ways that would otherwise 422 or corrupt analytics,+ * all handled here:+ *+ * - QUEUED execution. A request waits for whatever volunteer workers are+ * online, so a single call can take tens of seconds to minutes. Hence the+ * 120s timeout and the no-upstream-streaming design — one queued generation,+ * surfaced whole (streamChatCompletion emits it as a single delta).+ * - `max_tokens` must be >= 16 or the proxy 422s. We floor it, and default it+ * when the caller omits it so a worker doesn't run to its own (often large)+ * internal cap on every call.+ * - `stop` must be an ARRAY; a bare string 422s. We wrap it.+ * - No tool / function calling. tools, tool_choice and parallel_tool_calls are+ * dropped so a tool-using caller doesn't 422 the whole request.+ * - `usage` comes back as `{"kudos": N}` with no token counts. We synthesize+ * prompt/completion/total token estimates (chars/4) so analytics, savings+ * math and per-model usage charts aren't uniformly zero.+ * - Auth: anonymous access works with the documented sentinel key `0000000000`+ * (lowest queue priority). Registered keyless so the gateway auto-configures+ * it; a real aihorde.net key stored on the api_keys row is forwarded instead+ * for higher priority (see resolveBearer).+ *+ * Quality caveat (not fixable here): some workers append template/instruction+ * text after the answer. Surfaced verbatim; documented as a catalog quirk.+ */+const ANON_KEY = '0000000000';+const MIN_MAX_TOKENS = 16;+const DEFAULT_MAX_TOKENS = 512;+const HORDE_TIMEOUT_MS = 120000;++/** Rough token estimate (~4 chars/token) used only to fill usage when the proxy+ * returns kudos instead of token counts. Good enough for analytics, never+ * billed against anything. Handles string | null | multimodal-array content. */+function estimateTokens(content: ChatContent | undefined): number {+ if (content == null) return 0;+ let text: string;+ if (typeof content === 'string') {+ text = content;+ } else {+ text = content+ .map(block => (typeof block === 'string' ? block : (block?.text ?? '')))+ .join(' ');+ }+ return Math.ceil(text.length / 4);+}++export class AIHordeProvider extends BaseProvider {+ readonly platform: Platform = 'aihorde';+ readonly name = 'AI Horde';+ /** Works out of the box via the anonymous key: the gateway stores a sentinel+ * row (so routing treats the platform as configured) and we send the anon+ * bearer. A stored real horde key replaces the sentinel for higher priority. */+ keyless = true;+ private readonly baseUrl = 'https://oai.aihorde.net/v1';++ /** Map the stored credential to the bearer we send upstream. The keyless flow+ * stores `'no-key'` (or nothing) for the anonymous case → send AI Horde's+ * documented anonymous key. Any other stored value is treated as a registered+ * key and forwarded verbatim for higher queue priority. */+ private resolveBearer(apiKey: string): string {+ const k = apiKey?.trim();+ if (!k || k === 'no-key' || k === ANON_KEY) return ANON_KEY;+ return k;+ }++ /** Build the upstream body, normalizing the OpenAI params the proxy rejects+ * (see class doc). No `stream` — we never stream upstream. */+ private buildBody(messages: ChatMessage[], modelId: string, options?: CompletionOptions): Record<string, unknown> {+ const body: Record<string, unknown> = {+ model: modelId,+ messages,+ // Floor at 16 (proxy 422s below it); default when omitted.+ max_tokens: Math.max(MIN_MAX_TOKENS, options?.max_tokens ?? DEFAULT_MAX_TOKENS),+ };+ if (options?.temperature != null) body.temperature = options.temperature;+ if (options?.top_p != null) body.top_p = options.top_p;+ // `stop` must be an array; wrap a bare string, pass arrays through.+ if (options?.stop != null) {+ body.stop = Array.isArray(options.stop) ? options.stop : [options.stop];+ }+ // tools / tool_choice / parallel_tool_calls intentionally dropped: no tool support.+ return body;+ }++ /** Replace the proxy's `{"kudos": N}` usage with synthesized token counts so+ * downstream analytics aren't all zero. Prompt from the input messages,+ * completion from the returned content. */+ private synthesizeUsage(messages: ChatMessage[], data: ChatCompletionResponse): void {+ const prompt = messages.reduce((sum, m) => sum + estimateTokens(m.content), 0);+ const completion = (data.choices ?? []).reduce(+ (sum, c) => sum + estimateTokens(c.message?.content),+ 0,+ );+ data.usage = {+ prompt_tokens: prompt,+ completion_tokens: completion,+ total_tokens: prompt + completion,+ };+ }++ private parseError(err: unknown, status: number, statusText: string): string {+ // AI Horde errors are `{"detail": "..."}`; fall back to OpenAI's+ // `{error:{message}}` shape and then the status line.+ const detail = (err as { detail?: unknown })?.detail;+ if (typeof detail === 'string' && detail.length > 0) return detail;+ const msg = (err as { error?: { message?: unknown } })?.error?.message;+ if (typeof msg === 'string' && msg.length > 0) return msg;+ return statusText || `HTTP ${status}`;+ }++ async chatCompletion(+ apiKey: string,+ messages: ChatMessage[],+ modelId: string,+ options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,+ ): Promise<ChatCompletionResponse> {+ const res = await this.fetchWithTimeout(`${this.baseUrl}/chat/completions`, {+ method: 'POST',+ headers: {+ 'Authorization': `Bearer ${this.resolveBearer(apiKey)}`,+ 'Content-Type': 'application/json',+ },+ body: JSON.stringify(this.buildBody(messages, modelId, options)),+ }, options?.timeoutMs ?? HORDE_TIMEOUT_MS);++ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'chat/completions',+ });++ if (!res.ok) {+ const err = await res.json().catch(() => ({}));+ throw providerHttpError(res, `${this.name} API error ${res.status}: ${this.parseError(err, res.status, res.statusText)}`);+ }++ const data = await res.json() as ChatCompletionResponse;+ this.synthesizeUsage(messages, data);+ data._routed_via = { platform: this.platform, model: modelId };+ return data;+ }++ /**+ * AI Horde's proxy returns a queued generation as one response, so there is no+ * meaningful token-by-token stream. We run the same blocking call and emit the+ * result as a minimal SSE sequence (role → content → finish) so streaming+ * clients still work.+ */+ async *streamChatCompletion(+ apiKey: string,+ messages: ChatMessage[],+ modelId: string,+ options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,+ ): AsyncGenerator<ChatCompletionChunk> {+ const data = await this.chatCompletion(apiKey, messages, modelId, options, quotaContext);+ const choice = data.choices?.[0];+ const content = typeof choice?.message?.content === 'string' ? choice.message.content : '';+ const base = {+ id: data.id ?? this.makeId(),+ object: 'chat.completion.chunk' as const,+ created: data.created ?? Math.floor(Date.now() / 1000),+ model: modelId,+ };+ yield { ...base, choices: [{ index: 0, delta: { role: 'assistant' }, finish_reason: null }] };+ if (content) {+ yield { ...base, choices: [{ index: 0, delta: { content }, finish_reason: null }] };+ }+ yield { ...base, choices: [{ index: 0, delta: {}, finish_reason: choice?.finish_reason ?? 'stop' }] };+ }++ /**+ * The OpenAI proxy's GET /v1/models answers 200 for ANY bearer (it does not+ * validate the key), and the anonymous key is always usable, so a reachable+ * endpoint means the platform is healthy. Mirrors keyless providers: only a+ * confirmed 401/403 is treated as an invalid key. Transport errors propagate+ * to health.ts (marked status='error' without counting a failure).+ */+ async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean> {+ const res = await this.fetchWithTimeout(`${this.baseUrl}/models`, {+ method: 'GET',+ headers: { 'Authorization': `Bearer ${this.resolveBearer(apiKey)}` },+ }, 30000);+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'models',+ });+ return res.status !== 401 && res.status !== 403;+ }+}diff --git a/server/src/providers/index.ts b/server/src/providers/index.tsindex fa632d48..bfb719e9 100644--- a/server/src/providers/index.ts+++ b/server/src/providers/index.ts@@ -4,6 +4,7 @@ import { GoogleProvider } from './google.js';import { OpenAICompatProvider } from './openai-compat.js';import { CohereProvider } from './cohere.js';import { CloudflareProvider } from './cloudflare.js';+import { AIHordeProvider } from './aihorde.js';const providers = new Map<Platform, BaseProvider>();@@ -267,6 +268,16 @@ register(new OpenAICompatProvider({baseUrl: 'https://api.ainative.studio/api/v1',}));+// AI Horde — free, community-powered inference (volunteer workers) via an+// OpenAI-compatible proxy. Dedicated AIHordeProvider (not OpenAICompatProvider)+// because the proxy is queue-based and diverges from the OpenAI contract:+// max_tokens must be >=16, stop must be an array, no tool calling, usage is+// reported as kudos (synthesized into token counts), and calls can take tens of+// seconds (120s timeout, no upstream streaming). Registered keyless so it+// auto-configures and works anonymously (key 0000000000, lowest queue+// priority); a registered aihorde.net key raises priority. See issue #345.+register(new AIHordeProvider());+// Placeholder so getProvider('custom')/hasProvider('custom')/getAllProviders()// behave — but the real instance is built per-key by resolveProvider(), since// a custom provider's base URL is user-supplied and lives on the api_keys row.diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.tsindex 86fd8312..d373e662 100644--- a/server/src/routes/keys.ts+++ b/server/src/routes/keys.ts@@ -15,7 +15,7 @@ const PLATFORMS = ['google', 'groq', 'cerebras', 'nvidia', 'mistral','openrouter', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama','kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'ovh', 'agnes', 'reka', 'siliconflow',- 'routeway', 'bazaarlink', 'ainative', 'custom',+ 'routeway', 'bazaarlink', 'ainative', 'aihorde', 'custom',] as const;// `key` is optional so keyless providers (Kilo's anonymous gateway) can be addeddiff --git a/server/src/services/provider-quota.ts b/server/src/services/provider-quota.tsindex 846f2386..d6113ce0 100644--- a/server/src/services/provider-quota.ts+++ b/server/src/services/provider-quota.ts@@ -134,6 +134,10 @@ function inferPoolForPlatform(platform: Platform, modelId?: string | null): striif (platform === 'kilo') return 'kilo::anonymous';if (platform === 'pollinations') return 'pollinations::anonymous';if (platform === 'llm7') return 'llm7::anonymous';+ // AI Horde: anonymous requests share one queue priority (the 0000000000 key),+ // so they pool together; a registered key has its own kudos priority but we+ // still bucket per-platform here.+ if (platform === 'aihorde') return 'aihorde::anonymous';if (platform === 'huggingface') return 'huggingface::router';if (platform === 'opencode') return 'opencode::promo';// Aggregators with a single shared free pool across all ':free'/'auto:free' models.@@ -144,7 +148,7 @@ function inferPoolForPlatform(platform: Platform, modelId?: string | null): stri}function isSharedPool(platform: Platform): boolean {- return ['openrouter', 'google', 'groq', 'cerebras', 'sambanova', 'nvidia', 'mistral', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama', 'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'routeway', 'bazaarlink', 'ainative'].includes(platform);+ return ['openrouter', 'google', 'groq', 'cerebras', 'sambanova', 'nvidia', 'mistral', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama', 'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'routeway', 'bazaarlink', 'ainative', 'aihorde'].includes(platform);}type HeaderSpec = { metric: QuotaMetric; limit: string; remaining?: string; reset?: string; strategy?: QuotaResetStrategy };diff --git a/shared/types.ts b/shared/types.tsindex 1c1e0579..122b4d57 100644--- a/shared/types.ts+++ b/shared/types.ts@@ -53,6 +53,13 @@ export type Platform =// ~10M tokens/month free allocation (no card); quota unverified. Key from// ainative.studio.| 'ainative'+ // AI Horde — free, community-powered inference (volunteer workers) via an+ // OpenAI-compatible proxy (https://oai.aihorde.net/v1). Queue-based, so calls+ // can take tens of seconds; no tool support; usage is reported as kudos, not+ // tokens. Anonymous key `0000000000` works (lowest priority); a registered+ // aihorde.net key raises queue priority. Has a dedicated AIHordeProvider that+ // normalizes the proxy's OpenAI divergences. See issue #345.+ | 'aihorde'// User-configured OpenAI-compatible endpoint (llama.cpp, LM Studio, vLLM,// Ollama, any base_url). The endpoint URL lives on the api_keys row; see #117.| 'custom';