4 +title: Gratis Synthetic Free Provider
6 + - PX-RESEARCH-KMBSJUZR
7 + - PX-RESEARCH-LXU8HWNJ
8 + - PX-RESEARCH-KZ2M6WQ4
9 + - PX-RESEARCH-8WQ4KZ2M
10 + - PX-RESEARCH-Q7N4M2K9
13 +##
Gratis Synthetic Free Provider 15 +Extension `gratis` registers one synthetic Pi provider `grts` that exposes curated free-tier LLM backends as normal models.
16 +Intent: free inference with zero gratis-specific configuration; invisible when unusable.
20 +In: synthetic provider, model addressing, key resolution, backend visibility, failover cascade, free-model catalog for five backends.
21 +Out: paid models, key acquisition or signup flows, non-LLM free tiers (image, audio), usage accounting dashboards.
25 +Nested per-backend model IDs plus one synthetic router model.
26 +`<backend>` is one of `kilo`, `google`, `openrouter`, `groq`, `mistral`.
29 +grts/<backend>/<model> pinned: request routes to that backend only
30 +grts/auto router: request cascades across available backends
33 +`grts/auto` follows backend priority: kilo → google → openrouter → groq → mistral.
34 +Kilo leads because it is keyless and IP-budgeted: spend its anonymous quota before touching keyed quotas.
35 +Remaining order is by sustainable free budget (research: Gemini largest RPD/TPM; OpenRouter largest unlockable RPD; Groq, Mistral after).
36 +Within the kilo backend, virtual router models (`openrouter/free`, `kilo-auto/free`) rank first: they absorb upstream per-model saturation server-side (verified: pinned models 429 while virtual models answered in the same minute).
38 +####
Auto model parameters 40 +Pi holds model attributes per registered model entry, not per request (post-mortem failure 6).
41 +`grts/auto` therefore advertises the minimum context window and max output tokens across its candidate set, and the transport layer may tighten parameters per hop.
42 +An upstream context-overflow error on `grts/auto` normalizes to a recognized overflow error and advances the cascade exactly like exhaustion; pinned models surface it honestly.
46 +Per backend, evaluated independently at extension load:
48 +1. `GRATIS_<BACKEND>_TOKEN` (for example `GRATIS_OPENROUTER_TOKEN`)
49 +2. Native env of the backend (`OPENROUTER_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`)
50 +3. Pi's credential resolution for the backend's native provider id (`modelRegistry` auth lookup), which covers keys stored in the auth store and OAuth — env-only access is not required
53 +A backend that resolves a key by any step → its `grts/<backend>/*` models register.
54 +No backend resolves a key → `grts` never registers → provider invisible in `/model`.
55 +Partial keys → only resolved backends' models appear.
56 +**Kilo exception:** kilo is keyless — its free models register whenever the catalog is reachable, no key required.
57 +`GRATIS_KILO_TOKEN` or `KILO_API_KEY` optionally raise it above anonymous 200 req/h/IP and decouple it from shared egress IPs.
58 +Keys are read from process env only; gratis never prompts, stores, or logs key material.
60 +###
Transport and backends 62 +API type is a per-catalog-entry property, never a backend property; a single backend can serve several transports and the split can shift between catalog refreshes (post-mortem).
63 +All API types Pi implements are in scope from the start — the google backend alone needs its own API shape — and gratis does not assume openai-completions suffices.
64 +A catalog entry carries: model id, API type, endpoint base, context window, max output tokens, input modalities, reasoning flag.
66 +| Backend | Auth | Free models | Catalog source |
67 +| --- | --- | --- | --- |
68 +| kilo | none (key optional) | `:free` suffix + virtual `kilo-auto/free`, `openrouter/free` | live discovery via unauthenticated models endpoint |
69 +| google | Google account key | Flash class free tier | static curated |
70 +| openrouter | OpenRouter key | `:free` variants | live discovery via public models endpoint; static list as fallback |
71 +| groq | Groq key | free-tier models | static curated |
72 +| mistral | Mistral key | all models on Experiment plan | static curated |
74 +Free-set identification never relies on a suffix alone: discovery intersects live lists with a gratis-maintained free-set of names and patterns, updated with the catalog.
75 +Virtual router models advertise their published catalog parameters when present (`kilo-auto/free`: 256K ctx, 10K out); conservative fallback values apply only when nothing is published.
76 +Static catalogs are extension data; stale entries are corrected by catalog update, never by user config.
80 +Cascade applies to `grts/auto` only; pinned models surface errors honestly.
81 +Cascade operates at two granularities: models within a backend, then backends.
82 +Within an available backend, the router tries candidate models in catalog rank — virtual router models first — before cooling the backend; a 429 or quota response on one candidate advances to the next candidate.
83 +Only when every candidate fails does the backend cool until its window resets.
84 +An upstream context-overflow error on `grts/auto` advances the cascade without cooling; the router retries the same prompt on the next candidate or backend.
85 +The request fails only when every backend is cooling; the error then lists exhausted backends.
89 + [*] --> Available: backend available at load
90 + Available --> Cooling: 429 or quota exhausted
91 + Cooling --> Available: rate window resets
92 + Available --> [*]: unavailable at next load
93 + Cooling --> [*]: unavailable at next load
98 + req["grts/auto request"] --> pick{"backend available<br/>and not cooling?"}
99 + pick -->|yes| model["pick candidate model:<br/>virtual first"]
100 + pick -->|no| next["next backend"]
102 + model --> send["send"]
103 + send -->|success| done["stream response"]
104 + send -->|429 or quota,<br/>candidates remain| model
105 + send -->|429 or quota,<br/>candidates exhausted| cool["cool backend"] --> next
106 + send -->|overflow| next
107 + send -->|other error| err["surface error"]
112 +- Every routed model costs 0; gratis never emits paid-model fallbacks.
113 +- Free tiers commonly log or train on prompts; `grts` models are labeled in their description so users can avoid them for proprietary code.
114 +- Kilo's free pool rotates hard (post-mortem: every April 2026 ID is gone); discovery must tolerate arbitrary churn and empty pools.
115 +- Rate-limit and quota responses arrive status-wrapped with provider text in the body; failure classification inspects status and body text, never status alone.
116 +- Kilo exposes no rate-limit response headers; budget awareness is observation-based (cool on observed 429), never header-based.
117 +- opencode and Zen are rejected backends: the free tier is locked to the OpenCode client (403 `FreeTierError` even on a valid key); a Zen key grants paid models only. Neither returns for gratis unless OpenCode changes the lock (research: OpenCode Free Tier Lock).
118 +- Rate-limit metadata in catalogs is advisory, never user-facing config.
119 +- No new Pi config surface: `GRATIS_*` env vars are the only configuration gratis adds; native env and Pi's credential store are read, never written.
121 +###
Acceptance criteria 123 +- [ ] With no GRATIS-style and native keys set and network up, `grts/kilo/*` models appear and `grts/auto` includes kilo; all other `grts` backends stay invisible.
124 +- [ ] With no keys set and the Kilo catalog unreachable, `grts` does not appear in provider or model lists.
125 +- [ ] With exactly one native key set, only that backend's and kilo's models appear under `grts/`.
126 +- [ ] `GRATIS_OPENROUTER_TOKEN` overrides a simultaneously set native OpenRouter key.
127 +- [ ] A key stored in Pi's credential store for a native provider, with no env var set, registers the matching `grts` backend.
128 +- [ ] `grts/auto` on an exhausted first-priority backend completes on the next available backend without user action.
129 +- [ ] A context-overflow response during an `grts/auto` request advances the cascade; it never triggers cooling or fails while a next backend remains.
130 +- [ ] A pinned model that 429s returns the upstream error, not a cascade.
131 +- [ ] A pinned Kilo model returning upstream-saturation 429 while a virtual router model is available completes on that model without cooling the kilo backend.
132 +- [ ] Virtual models advertise published catalog parameters when present.
133 +- [ ] Catalog entries with non-openai-completions API types (anthropic-messages, google-shaped) stream correctly without conversion assumptions.
134 +- [ ] OpenRouter discovery with zero `:free` variants and Kilo discovery with zero `:free` models each yield no models for that backend and no error.
135 +- [ ] All registered models report input/output cost 0 and a free-tier data caveat in their description.