# How Tier-Based Model Selection Works in ULTRAPLINIAN (G0DM0D3)

> Discover how ULTRAPLINIAN’s tier-based model selection grants API access to specific LLMs based on user subscription plans, ensuring efficient parallel request processing.

- Repository: [pliny/G0DM0D3](https://github.com/elder-plinius/G0DM0D3)
- Tags: internals
- Published: 2026-07-19

---

**ULTRAPLINIAN uses a subscription-gated tier system that maps user plans to specific model pools, enforcing access control at the API gateway before parallelizing requests across whitelisted LLMs.**

The **tier-based model selection** system in ULTRAPLINIAN serves as the gatekeeper for G0DM0D3’s flagship racing mode. By linking subscription tiers to specific model pools, the platform controls computational costs while ensuring users receive responses from the fastest and most capable models their plan allows. This architecture enables parallel inference across multiple providers while maintaining strict access boundaries between free, pro, and enterprise users.

## Tier Definitions and Subscription Plans

The pay-wall logic resides in **[[`api/lib/tiers.ts`](https://github.com/elder-plinius/G0DM0D3/blob/main/api/lib/tiers.ts)](https://github.com/elder-plinius/G0DM0D3/blob/main/api/lib/tiers.ts)**. Each subscription plan—**free**, **pro**, and **enterprise**—defines an `ultraplinianTiers` array that explicitly whitelists which speed tiers the user may access.

| Plan | Allowed ULTRAPLINIAN Tiers |
|------|----------------------------|
| **free** | `['fast']` |
| **pro** | `['fast', 'standard', 'smart', 'power']` |
| **enterprise** | `['fast', 'standard', 'smart', 'power', 'ultra']` |

When a request arrives, the server calls `resolveTier` to map the API key to a `TierConfig` object. This configuration attaches to the request object as `req.tierConfig`, making the allowed tiers available for downstream validation.

## Request-Level Tier Validation

The ULTRAPLINIAN endpoint at `/v1/ultraplinian/completions` is implemented in **[[`api/routes/ultraplinian.ts`](https://github.com/elder-plinius/G0DM0D3/blob/main/api/routes/ultraplinian.ts)](https://github.com/elder-plinius/G0DM0D3/blob/main/api/routes/ultraplinian.ts)**. The handler performs a two-step validation before executing the model race:

1. **Parse the requested tier** – The client specifies a `tier` field in the JSON body. The server validates this against the `validTiers` array: `['fast', 'standard', 'smart', 'power', 'ultra']`.

2. **Enforce plan limits** – The handler checks `req.tierConfig.ultraplinianTiers` to verify the requested tier is permitted for the caller’s subscription.

If the tier is disallowed, the server returns HTTP **403** with a structured error message:

```typescript
const tierConfig = req.tierConfig
if (tierConfig && !tierConfig.ultraplinianTiers.includes(tier)) {
  res.status(403).json({
    error: 'Upgrade required',
    message: `The "${tier}" ULTRAPLINIAN tier requires a higher plan…`,
    allowed_tiers: tierConfig.ultraplinianTiers,
  })
  return
}

```

This explicit rejection provides the client with their exact allowed tiers, creating a transparent upgrade path.

## Mapping Tiers to Model Pools

Once validated, the abstract tier name expands into concrete model identifiers via **[[`api/lib/ultraplinian.ts`](https://github.com/elder-plinius/G0DM0D3/blob/main/api/lib/ultraplinian.ts)](https://github.com/elder-plinius/G0DM0D3/blob/main/api/lib/ultraplinian.ts)**. This file contains the static `ULTRAPLINIAN_MODELS` catalog and helper functions that compile cumulative model lists.

### The Cumulative Tier System

Higher tiers inherit all models from lower tiers, ensuring that a `smart` request still benefits from the speed and cost advantages of `fast` models.

The `getModelsForTier` function implements this cumulative logic:

```typescript
export function getModelsForTier(tier: SpeedTier): string[] {
  const tiers = ULTRAPLINIAN_MODELS
  switch (tier) {
    case 'fast':      return tiers.fast
    case 'standard':  return [...tiers.fast, ...tiers.standard]
    case 'smart':     return [...tiers.fast, ...tiers.standard, ...tiers.smart]
    case 'power':     return [...tiers.fast, ...tiers.standard, ...tiers.smart, ...tiers.power]
    case 'ultra':     return [...tiers.fast, ...tiers.standard, ...tiers.smart, ...tiers.power, ...tiers.ultra]
  }
}

```

For example, the `fast` tier contains 12 models, while the `power` tier expands to 53 models by aggregating all lower tiers plus additional high-capability models.

### Venice Provider Support

The system supports mixed-provider races through `getVeniceModelsForTier`, which mirrors the cumulative logic for Venice-specific model slugs. When a Venice API key is present, the engine can race models across both standard and Venice providers simultaneously.

## End-to-End Request Flow

The complete **tier-based model selection** flow executes as follows:

1. **Client POST** to `/v1/ultraplinian/completions` with `tier: 'smart'` and authentication headers
2. **Authentication layer** resolves the API key to a subscription plan via `resolveTier` in [`api/lib/tiers.ts`](https://github.com/elder-plinius/G0DM0D3/blob/main/api/lib/tiers.ts)
3. **Validation layer** checks if `smart` exists in `req.tierConfig.ultraplinianTiers`; returns 403 if not
4. **Expansion layer** calls `getModelsForTier('smart')` to compile the cumulative model list
5. **Execution layer** invokes `raceModels` with the compiled list, parallelizing requests across all specified LLMs
6. **Response streaming** returns the highest-scoring response as an SSE stream, with potential leader upgrades as slower models complete

## Implementation Benefits

**Granular monetization** – By restricting high-cost models to enterprise tiers, the platform aligns infrastructure expenses with revenue tiers while maintaining service availability for free users.

**Performance guarantees** – The cumulative tier design ensures that upgrading from `fast` to `smart` never removes models from the pool; it only adds more capable options. This guarantees latency does not regress when requesting higher tiers.

**Explicit access control** – The 403 response schema includes `allowed_tiers` and `requested_tier` fields, enabling client applications to programmatically detect upgrade requirements without parsing error strings.

## Practical Usage Examples

### Successful Request on Pro Plan

The following curl request accesses the `standard` tier using a pro-level API key:

```bash
curl -X POST https://your-host/v1/ultraplinian/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Explain quantum tunnelling." }],
    "openrouter_api_key": "sk-pro-example",
    "tier": "standard",
    "autotune": true,
    "parseltongue": true,
    "stream": true
  }'

```

The server returns an SSE stream containing the best response from the cumulative `fast` + `standard` model pool.

### Forbidden Tier Response

Attempting to access the `smart` tier with a free plan API key triggers the access control mechanism:

```bash
curl -X POST https://your-host/v1/ultraplinian/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Summarise the French Revolution." }],
    "openrouter_api_key": "sk-free-example",
    "tier": "smart"
  }'

```

Result:

```json
{
  "error": "Upgrade required",
  "message": "The \"smart\" ULTRAPLINIAN tier requires a higher plan. Your \"free\" plan allows: fast.",
  "allowed_tiers": ["fast"],
  "requested_tier": "smart"
}

```

### Programmatic Tier Inspection

For custom tooling, import the tier expansion logic directly:

```typescript
import { getModelsForTier } from './api/lib/ultraplinian'

const tier: 'power' = 'power'
const models = getModelsForTier(tier)
console.log(models)
// Output: Array of 53 model slugs including fast, standard, smart, and power tiers

```

### Extending Model Pools

To add a new model to the `ultra` tier, modify **[[`api/lib/ultraplinian.ts`](https://github.com/elder-plinius/G0DM0D3/blob/main/api/lib/ultraplinian.ts)](https://github.com/elder-plinius/G0DM0D3/blob/main/api/lib/ultraplinian.ts)**:

```typescript
// Inside ULTRAPLINIAN_MODELS.ultra array:
'newprovider/new-model-xyz',

```

The model becomes immediately available to enterprise users requesting `tier: "ultra"` without requiring changes to the validation logic.

## Summary

- **Tier-based model selection** in ULTRAPLINIAN couples subscription plans to specific model pools through the `ultraplinianTiers` whitelist defined in [`api/lib/tiers.ts`](https://github.com/elder-plinius/G0DM0D3/blob/main/api/lib/tiers.ts)
- The system validates requests against plan limits in [`api/routes/ultraplinian.ts`](https://github.com/elder-plinius/G0DM0D3/blob/main/api/routes/ultraplinian.ts), returning HTTP 403 with explicit upgrade instructions for unauthorized tiers
- Model expansion follows a cumulative inheritance pattern where higher tiers aggregate all models from lower tiers via `getModelsForTier` in [`api/lib/ultraplinian.ts`](https://github.com/elder-plinius/G0DM0D3/blob/main/api/lib/ultraplinian.ts)
- Five speed tiers exist—**fast**, **standard**, **smart**, **power**, and **ultra**—with only **enterprise** plans accessing the full `ultra` tier
- Runtime configuration in [`src/store/index.ts`](https://github.com/elder-plinius/G0DM0D3/blob/main/src/store/index.ts) manages client-side defaults, but server-side enforcement in the API routes provides the authoritative access control

## Frequently Asked Questions

### What happens if I request a tier not included in my subscription plan?

The server returns an HTTP **403 Forbidden** response with a JSON payload containing the `error: "Upgrade required"` field, a human-readable message explaining the limitation, and an `allowed_tiers` array listing exactly which tiers your current plan supports. This enables your application to detect the restriction programmatically and prompt users to upgrade.

### How does ULTRAPLINIAN handle the "ultra" tier differently from other tiers?

The **ultra** tier is exclusive to **enterprise** subscriptions as defined in [`api/lib/tiers.ts`](https://github.com/elder-plinius/G0DM0D3/blob/main/api/lib/tiers.ts). Unlike lower tiers, `ultra` typically includes the most expensive, high-capability models (such as frontier models with extended context windows) and represents the complete cumulative pool of all available models in the system.

### Can I see which specific models are included in each tier before making a request?

Yes. You can inspect the `ULTRAPLINIAN_MODELS` object in [`api/lib/ultraplinian.ts`](https://github.com/elder-plinius/G0DM0D3/blob/main/api/lib/ultraplinian.ts) or call the `getModelsForTier` utility function programmatically to retrieve the exact array of model slugs for any tier. The `fast` tier starts with 12 models, while `power` expands to 53 models through cumulative inheritance.

### Why does ULTRAPLINIAN use a cumulative tier system rather than discrete model groups?

The cumulative design ensures that requesting a higher tier like `smart` never removes access to faster or cheaper `fast` tier models. This guarantees that latency and throughput do not degrade when upgrading tiers; the system simply adds more capable models to the race while retaining the reliable baseline options.