Clef and AI Gateway

Clef is a decision layer: it selects, sequences, and prioritizes existing cards. It does not generate flashcard content.

• Code lives in packages/api/src/services/ai/: gateway-client.ts, clef.ts, schemas.ts, cache.ts, evaluation-service.ts.
• Only the API calls AI Gateway / Workers AI; the browser never sees credentials.
• Every evaluation records model, input hash, schema, result, confidence, and gateway request id in ai_evaluations.
• Deterministic evaluations are cached by input hash + schema version.
• Bulk imports enqueue evaluations instead of blocking the request.

Configuration

AI_GATEWAY_URL=https://gateway.ai.cloudflare.com/v1/<account>/<gateway>
AI_GATEWAY_TOKEN=<secret>
CLEF_MODEL=@cf/meta/llama-3.1-8b-instruct

When AI_GATEWAY_URL/AI_GATEWAY_TOKEN are unset, the Worker uses the Workers AI AI binding; when neither is available, evaluations are marked skipped.

Failure behaviour

Failure	Behaviour
Gateway timeout	Return fallback scheduler plan
Clef unavailable	Mark evaluation failed; continue study
Low confidence	Use deterministic thresholds
Invalid output	Reject evaluation and log diagnostic
Rate limit	Queue or defer evaluation