OposIA
Prepare your civil-service exam with tests generated from the official syllabus.
99.93% available over 24 h · Updated last month · History

The problem
Preparing a Spanish civil-service exam means memorising a long official syllabus and practising with tests that mirror the real thing: same format, same penalty, same time limit.
Generic question generators invent content or mix sources. Here every question has to come from that specific syllabus and be traceable to its topic.
The approach
One vector index per exam, built from the official syllabus page by page: every passage knows which document and page it comes from.
One mode per task — study a topic, generate questions, mock exam, summary, review or chat — each with its own prompt and as many passages as it needs.
Two filters before answering: a threshold on the reranker score and a prompt that only admits retrieved text. If it is not in the syllabus, the assistant says so without calling the model.
A question bank in PostgreSQL: every generated question is stored with its topic, page and statistics. A quiz takes half from the bank (questions that person has not seen) and generates the other half in the background, in batches of 10 that mix topics; grading happens server-side and the correct answer never reaches the browser early.
Architecture
React + Vite frontend (study, questions, timed exam, progress, chat and dashboard pages) served by nginx.
FastAPI API; ingestion with PyMuPDF (text rebuilt from coordinates, tesseract OCR for scanned pages) and LlamaIndex over ChromaDB (one collection per exam).
Cohere embed-multilingual-v3.0 embeddings; Cohere reranking; LLM through a cascade of five models across three providers (Groq gpt-oss-120b and 20b, Mistral ministral-14b, Groq qwen3.8-27b, Gemini 3.6-flash) over OpenAI-compatible APIs; Ollama locally.
PostgreSQL for exams, the question bank, progress and accounts; Redis for sessions. Docker, deployed with Coolify behind Cloudflare. Two nightly cron jobs: fill the bank and judge it.
Accounts: email link (Resend), email and password (bcrypt) or Google (ID token verified server-side). The app works the same without an account; on sign-up, anonymous progress is merged into it.
Decisions that mattered
256-token chunks with 30 overlap instead of 512: exam questions need precise passages, not long paragraphs.
8× oversampling in the vector search followed by reranking: retrieve many cheap candidates, let the reranker pick the 4–12 that reach the model.
Query embeddings with input_type search_query and document embeddings with search_document: Cohere treats them differently and retrieval quality improves.
The full-syllabus PDF index is excluded from retrieval so it does not overshadow the individual topics.
History capped at the last 8 messages and context at 6,000 characters to stay within Groq's free-tier 8,000 tokens/minute: the chat went from dying on the sixth question to holding fourteen in a row, and median latency dropped from 4 s to 3 s.
The reranker-score threshold was measured in production, not guessed: an off-syllabus question scores 0.0005 and a weak but relevant one 0.07, so the cut-off is 0.02 and the model itself is the second filter (it answers NO_KB when the passages are not about the question).
PDF text rebuilt from coordinates (PyMuPDF) instead of flat extraction: syllabus tables and columns used to come out scrambled. Each page is a document with its number, and chunks have deterministic ids: re-ingesting never duplicates.
The model is an environment variable, not code: when Groq retired llama-3.1-8b (September 2026), the migration was a configuration change. Qwen3-27B was ruled out by its 1,000 output-tokens/minute cap on the free tier; gpt-oss-120b has none.
gpt-oss models reason before answering and that reasoning counts against max_tokens: at 4,096 the 10-question JSON came back truncated in most batches. Generation now asks for 8,192 tokens with reasoning_effort=low, and complete questions are salvaged from a truncated JSON instead of discarding the batch.
Passages are numbered in the prompt and the model declares which one each question comes from: topic and page are exact, not whatever the model writes. Any question that points at the material ("according to fragment 3…") is discarded and regenerated, because the candidate never sees the text.
Lexical search on top of the vector search: legal references ("art. 24", "Ley 39/2015") and literal phrases are looked up verbatim in the index and added to the candidates before reranking. The retrieval evaluation went from 7/9 to 9/9.
No paid inference: instead of one model plus a fallback, a cascade of five free models across three providers. A 429 quarantines the model and moves to the next; a 404 retires it; at start-up and every 24 hours the list is checked against the provider catalogue. When Groq retired two models at once, nothing had to change. The bank is filled overnight with the day's quotas, so by day questions come from the bank instantly.
The topic comes from the folder, not the model: the Diagnostic Imaging syllabus arrived in 30 numbered folders ("6. Abdomen y Vías Biliares"), so every passage carries its folder and the citation reads "Tema 6 · 1. Abdomen.pdf, p. 12". Mock exams sample per topic with equal weight, not per file.
A judge for the bank, not for every answer: each question is evaluated once against its source passage on six criteria (grounded, correct key, single correct option, self-contained, plausible distractors, clear). The first three are fatal and retire the question. The score is deterministic (criteria met / 6): the model describes, it does not grade. And since options are shuffled afterwards, the judge reasons about option text, never letters.
The first evaluation exposed the typical failure: questions citing laws or articles that were not in the passage. Fixed in the generation prompt (only what the text says; the answer must be confirmable in it) and the next batch dropped from 17% to 9% invalid. Three reports from different users retire a question even if the judge approved it.
Frictionless identity: the app is usable anonymously (30 days in that browser) and the account is optional. An account is an email with a canonical session; signing in from another device merges anonymous progress (per-topic counters summed, exams moved, seen questions deduplicated) and never adopts a session that already belongs to someone else. Email-link tokens are stored hashed and work once.
Results
In production at oposiciones.iana-ai.com with two exams: Social Work (41 documents, 27 topics, 4,550 passages) and Diagnostic Imaging (57 documents, 30 topics, 3,297 passages). Every passage knows its topic, file and page.
A bank of 2,677 questions (22 Sep 2026) generated overnight on free quotas. 1,160 judged against their source passage: 84% valid; the rest are retired before anyone sees them. By generating model, gpt-oss-120b gets 94% right, ministral-14b and gpt-oss-20b between 75% and 87%.
Chat with citations in both exams: 6 of 6 control questions cite topic and page; median 2.9 s. Social Work retrieval evaluation: 9 of 9, and the off-syllabus question gets the fixed reply without calling the model.
10-question practice: 8 come from the bank instantly and all 10 are ready in 2.4–4.5 s. 100-question mock with the real format (1/3 penalty, pass mark 5): 50 instantly and the rest while answering.
Inference cost: €0/month. Groq retired two models in July and the cascade carried on by itself.
Mobile Lighthouse on the landing page: performance 93, accessibility 100, best practices 100, SEO 100. CSP, immutable asset caching, HSTS and Cloudflare proxy.
Accounts via email link, password or Google; privacy policy and in-app account deletion.
Next
- A visual identity of its own: palette, typography and icons instead of system emoji
- A third exam (Administration Manager) as soon as its syllabus arrives
- Drain the judge queue (150 questions a night) and publish the per-model valid rate continuously
- Capacity for real usage: the free cascade adds up to roughly 400,000 tokens/day on Groq plus Mistral and Gemini; with dozens of active candidates a paid tier will be needed