D-viva-assistant-agent

Project overview

Role Sole builder — product design, architecture, database layer, LLM integration, validation and tests

Scenario

Existing viva prep tools are either generic flashcard apps or require hand-crafting every question. The real bottleneck is grounding: an AI examiner is only useful if its questions trace back to what the thesis actually says, and scoring is only trustworthy if it cites the evidence it used.

Product strategy

I built a private desktop workflow where the thesis is ingested into evidence blocks, practice questions and scoring cite those blocks, and low-scoring answers feed a review queue. The app keeps files and history local unless the user opts into a provider.

Evaluation

I used the app throughout real thesis defence preparation, checking whether questions trace back to the thesis, feedback leads to a concrete revision, and weak answers return to a usable review queue.

Outcome and current stage

Shipped local-first viva prep app · evidence-linked practice · privacy-first desktop use

My contribution

Thesis ingest pipeline — PDF / MD / TXT → paragraph evidence blocks with a quality report; every downstream AI call is grounded to ingest output, not model priors
AI study pack generation — thesis summary, key numbers, method Q&A, high-pressure Q&A, and literature cards; each item cites the evidence block it came from and passes a pre-persist validator
Editable prep items, revalidation, review queue, and a training plan generator with a static fallback when no model key is configured
Real-time AI examiner — draws questions from evidence blocks, scores responses on five dimensions (accuracy / depth / language / methodology / poise) with diagnosis, English rewrite, and follow-up
STT practice loop — record answer → transcribe (browser Web Speech or Google Cloud STT) → score; low-scoring items feed the review repair board
Provider-agnostic LLM layer — AI SDK v6 generateObject + Zod for structured scoring; supports Gemini / Claude / OpenAI; graceful no-key degradation (practice + transcripts still work)
Electron + electron-builder macOS packaging for a private, single-user desktop app

Technical evidence

Local-first data model: SQLite (better-sqlite3, WAL, FTS5) for theses, evidence blocks, study packs, and session history; DB lives entirely on device
Privacy-by-design: cloud AI is opt-in with explicit disclosure of what is sent to which provider; API keys stay in .env.local (gitignored), logs are redacted, and recordings remain local
Next.js App Router with server-only DB access (runtime=nodejs boundary, globalThis singleton, serverExternalPackages for better-sqlite3); AI calls gated behind env parse
Tests use MockLlmClient by default; real model calls are gated by RUN_LIVE_AI=1 and only run against public sample theses

Grounding every generated item

An imported thesis (PDF / Markdown / text) is extracted into paragraph evidence blocks with a quality report. Every downstream item — summary, key numbers, method Q&A, high-pressure Q&A, literature cards, and training plan — is bound to an evidence block and passes a pre-persist validator. The judge and examiner base their decisions on bound evidence.

The examiner loop

A real-time examiner draws questions from evidence blocks and scores a response across five dimensions, with a diagnosis, an English rewrite, and a follow-up. You can type or paste an answer, or record one — the audio is transcribed (browser Web Speech or Google Cloud STT) and scored. Low-scoring items feed the review queue and repair board.

Local-first, cloud AI opt-in

The SQLite library, recordings, and thesis files stay on the device. Cloud AI is optional and activates when a provider key is present, with a clear preview of what will be sent and to which provider; practice and transcripts remain available in local mode.

The shipped product is a private, single-user desktop app. Its provider-agnostic LLM layer supports Gemini, Claude, and OpenAI; tests use a mock client, while gated live checks run against public sample theses.