circuitforge-core/docs/modules/tiers.md

tiers

Tier system implementation. Provides the @require_tier() decorator used on FastAPI endpoints and the BYOK (bring your own key) unlock logic.

from circuitforge_core.tiers import require_tier, TierLevel

Tier levels

Tier	Constant	What it unlocks
Free	TierLevel.FREE	Core pipeline, basic AI assist, local LLM only
Paid	TierLevel.PAID	Cloud LLM, integrations, full AI generation suite
Premium	TierLevel.PREMIUM	Fine-tuned models, multi-user, advanced analytics
Ultra	TierLevel.ULTRA	Human-in-the-loop operator execution

BYOK unlocks

Users who configure their own LLM backend (via config/llm.yaml) can unlock features that would otherwise require a paid tier. The tiers module checks for configured BYOK backends before enforcing tier gates.

This is intentional: privacy-preserving self-hosting is rewarded, not penalized. A user running their own Ollama instance gets AI features without a subscription.

@require_tier(tier: str)

Decorator for FastAPI route handlers. Resolves the calling user's tier from the request context (Heimdall JWT, validated by Caddy) and raises HTTP 403 if insufficient.

from circuitforge_core.tiers import require_tier

@router.post("/recipes/suggest")
@require_tier("paid")
async def suggest_recipes(request: Request, body: SuggestRequest):
    ...

In local (non-cloud) mode with no license configured, all users default to free. BYOK detection runs first — if a local LLM backend is configured, relevant paid features unlock regardless of license tier.

Per-product overrides

Products define which specific features are gated at which tier in their own app/tiers.py, using the cf-core decorators as building blocks. The cf-core tiers module provides the mechanism; the product owns the policy.

# kiwi/app/tiers.py
from circuitforge_core.tiers import require_tier

# Re-export with product-specific names if desired
require_paid = require_tier("paid")
require_premium = require_tier("premium")

# BYOK unlockable features — defined per product
BYOK_UNLOCKABLE = [
    "recipe_suggestion_l3",
    "receipt_ocr",
    "expiry_llm_fallback",
]

Checking tier in non-endpoint code

from circuitforge_core.tiers import get_user_tier, TierLevel

tier = get_user_tier(user_id)
if tier >= TierLevel.PAID:
    # run AI feature