From e5a32a4602f9dba6892bbf215551ac3f5cb83281 Mon Sep 17 00:00:00 2001 From: im-rk Date: Sat, 3 Oct 2026 15:56:15 +0530 Subject: [PATCH 1/4] feat(ask): reuse an identical recent answer instead of calling the AI again, and fix Hindi punctuation --- migrations/007_answer_cache.sql | 8 ++++ package.json | 1 + scripts/prewarm.mjs | 66 +++++++++++++++++++++++++++++++++ src/app/api/ask/route.ts | 15 +++++++- src/lib/answer.ts | 4 +- src/lib/answers.ts | 34 ++++++++++++++++- src/lib/language.ts | 7 ++++ src/lib/question-key.ts | 12 ++++++ tests/unit/question-key.test.ts | 42 +++++++++++++++++++++ 9 files changed, 183 insertions(+), 6 deletions(-) create mode 100644 migrations/007_answer_cache.sql create mode 100644 scripts/prewarm.mjs create mode 100644 src/lib/question-key.ts create mode 100644 tests/unit/question-key.test.ts diff --git a/migrations/007_answer_cache.sql b/migrations/007_answer_cache.sql new file mode 100644 index 0000000..1ba83b6 --- /dev/null +++ b/migrations/007_answer_cache.sql @@ -0,0 +1,8 @@ +-- Answer reuse: an identical question gets the stored answer back instead of another AI call. +-- question_key is the question normalised (src/lib/question-key.ts); lecture_id is the session an Ask was +-- scoped to (NULL = the whole library), so a session-scoped answer is never served to a library-wide ask. +-- Older rows have NULLs, so they are never matched. Backwards compatible: code from before this migration +-- keeps working (it just doesn't fill the new columns). +ALTER TABLE answers ADD COLUMN question_key TEXT; +ALTER TABLE answers ADD COLUMN lecture_id UUID; +CREATE INDEX idx_answers_cache ON answers (question_key, created_at DESC) WHERE question_key IS NOT NULL; diff --git a/package.json b/package.json index b411707..56610b1 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,7 @@ "test": "vitest run", "test:e2e": "playwright test", "eval:ask": "node scripts/eval-ask.mjs", + "prewarm": "node scripts/prewarm.mjs", "db:migrate": "node scripts/migrate.mjs", "spike": "node scripts/spike.mjs", "e2e:local": "node scripts/e2e-local.mjs", diff --git a/scripts/prewarm.mjs b/scripts/prewarm.mjs new file mode 100644 index 0000000..80e7ef7 --- /dev/null +++ b/scripts/prewarm.mjs @@ -0,0 +1,66 @@ +// Warms a deployed Pravaha before a demo or judging, so the first real visitor gets instant results: +// APP_URL=https://pravaha-cyan.vercel.app pnpm prewarm +// 1. Asks each demo question once. The answer is stored and then reused for 24 hours (or until a session +// changes), so judges asking the same thing get it instantly and spend no AI quota. +// 2. Opens each answer's reel, so Cloudinary has already generated it. +// 3. Opens every shared concept's Compare Reel and builds a couple of Learning Paths. +// It spends a few Cloudinary credits (reels are generated once, then cached on the CDN), so it checks +// /api/status first and stops if credits are nearly gone. +import { readFileSync } from "node:fs"; + +const base = (process.env.APP_URL ?? "").replace(/\/$/, ""); +if (!base) throw new Error("Set APP_URL, e.g. APP_URL=https://pravaha-cyan.vercel.app pnpm prewarm"); + +const { questions } = JSON.parse(readFileSync(new URL("../tests/eval/ask-questions.json", import.meta.url), "utf8")); +const EXTRA_QUESTIONS = ["What is the bias-variance trade-off?", "Why should the learning rate decrease during training?"]; +const TOPICS = ["Choosing a learning rate", "Overfitting and underfitting"]; +const sleep = (ms) => new Promise((r) => setTimeout(r, ms)); +const json = (path, init) => fetch(base + path, init).then((r) => r.json()); + +// Cloudinary answers 423 while it analyses a video and then serves it; poll until it does (or give up). +async function warm(url, label) { + const started = Date.now(); + for (let i = 0; i < 12; i++) { + try { + const res = await fetch(url, { method: "HEAD" }); + if (res.ok) return console.log(` ok ${label} (${Math.round((Date.now() - started) / 1000)}s)`); + if (res.status !== 423 && res.status !== 202) return console.log(` FAIL ${label}: ${res.status} ${res.headers.get("x-cld-error") ?? ""}`); + } catch { + /* retry */ + } + await sleep(4000); + } + console.log(` slow ${label}: still generating after 48s`); +} + +const status = await json("/api/status").catch(() => null); +if (status?.cloudinary) { + console.log(`Cloudinary credits: ${status.cloudinary.used} of ${status.cloudinary.limit} (${status.cloudinary.pct}%)`); + if (status.cloudinary.pct >= 90) throw new Error("Credits are above 90%: not warming anything that would spend more."); +} + +console.log("\n1. Questions and their reels"); +for (const q of [...questions.map((x) => x.q), ...EXTRA_QUESTIONS]) { + if (q.startsWith("REPLACE")) continue; + const started = Date.now(); + const res = await json("/api/ask", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ question: q }) }).catch((e) => ({ status: `error ${e.message}` })); + console.log(` ${String(res.status).padEnd(10)} ${Math.round((Date.now() - started) / 1000)}s ${res.cached ? "(reused) " : ""}${q.slice(0, 70)}`); + if (res.reel?.url && res.reel.clips > 1) await warm(res.reel.url, "answer reel"); +} + +console.log("\n2. Compare reels"); +const concepts = (await json("/api/concepts").catch(() => [])).filter((c) => c.sessions > 1).slice(0, 4); +for (const c of concepts) { + const html = await fetch(`${base}/concepts/${c.key}`).then((r) => r.text()); + const reel = html.match(/https:\/\/res\.cloudinary\.com[^"' <]*fl_splice[^"' <]*\.mp4/)?.[0]?.replaceAll("&", "&"); + console.log(` ${c.name}`); + if (reel) await warm(reel, "compare reel"); +} + +console.log("\n3. Learning Paths"); +for (const topic of TOPICS) { + const res = await json("/api/paths", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ topic }) }).catch(() => ({})); + console.log(` ${res.status ?? "error"} ${topic}`); + if (res.path?.reel?.url) await warm(res.path.reel.url, "course reel"); +} +console.log("\nDone. Answers are reused for 24 hours, or until a session is added, published or changed."); diff --git a/src/app/api/ask/route.ts b/src/app/api/ask/route.ts index 4568aba..d8a1b62 100644 --- a/src/app/api/ask/route.ts +++ b/src/app/api/ask/route.ts @@ -1,7 +1,7 @@ import { after, NextResponse } from "next/server"; import { z } from "zod"; -import { saveAnswer } from "@/lib/answers"; +import { findCachedAnswer, saveAnswer } from "@/lib/answers"; import { cleanFollowUps, validateAnswer } from "@/lib/citations"; import { AiUnconfigured } from "@/lib/ai"; import { askGrounded } from "@/lib/answer"; @@ -64,6 +64,17 @@ async function ask(question: string, lectureId: string | null, progress: (p: Pro // aren't stored as shareable links (they would outlive the video). const trial = lectureId ? Boolean((await getLecture(lectureId))?.trialExpiresAt) : false; const logged = (...args: Parameters) => (trial ? Promise.resolve() : logAsk(...args)); + // The same question was answered recently and nothing in the library has changed: reuse that answer. No retrieval, + // no AI call (so no quota, and instant), same citations and share link. Still counted in Insights. + const cachedAnswer = trial ? null : await findCachedAnswer(question, lectureId); + const cachedResult = cachedAnswer?.result as { citations?: { lectureId: string; title: string }[] } | undefined; + if (cachedAnswer && cachedResult?.citations?.length) { + const sessions = [...new Set(cachedResult.citations.map((c) => c.title))].slice(0, 5); + progress({ type: "retrieved", moments: cachedResult.citations.length, sessions, expanded: false }); + log("ask.cache_hit", { cited: cachedResult.citations.length, ms: Date.now() - started }); + after(() => logged(question, "answered", cachedResult.citations!.map((c) => c.lectureId))); + return { ...cachedAnswer.result, answerId: cachedAnswer.id, cached: true }; + } // A question in Hindi (or any non-Latin script) is searched in English; the answer stays in its language. const { hits: matched, expanded } = await retrieve(question, lectureId, progress); // In one session, a question with no keyword match ("What is this about?") is answered from moments across @@ -100,7 +111,7 @@ async function ask(question: string, lectureId: string | null, progress: (p: Pro followUps: result.status === "answered" ? cleanFollowUps(raw.follow_ups, question) : [], }; // Stored as shown, so /a/[answerId] can be shared without re-running the model. - const answerId = result.status === "answered" && !trial ? await saveAnswer(question, body) : null; + const answerId = result.status === "answered" && !trial ? await saveAnswer(question, body, lectureId) : null; return { ...body, answerId }; } catch (error) { // NFR4: the model failing never means an error page — show the most relevant moments instead. diff --git a/src/lib/answer.ts b/src/lib/answer.ts index 5f63d8f..5a131b6 100644 --- a/src/lib/answer.ts +++ b/src/lib/answer.ts @@ -4,7 +4,7 @@ import { z } from "zod"; import { generateJson } from "@/lib/ai"; import type { RawAnswer } from "@/lib/citations"; import { formatTime } from "@/lib/format"; -import { answerLanguage } from "@/lib/language"; +import { answerLanguage, fixPunctuation } from "@/lib/language"; import type { Hit } from "@/lib/search"; const Answer = z.object({ @@ -48,5 +48,5 @@ export async function askGrounded(question: string, hits: Hit[], { budgetMs }: { : SYSTEM, prompt: `${excerpts(hits)}\n\nQuestion: ${question}`, }); - return data; + return language ? { ...data, answer: fixPunctuation(data.answer, language), follow_ups: data.follow_ups.map((f) => fixPunctuation(f, language)) } : data; } diff --git a/src/lib/answers.ts b/src/lib/answers.ts index d352f74..9b4f715 100644 --- a/src/lib/answers.ts +++ b/src/lib/answers.ts @@ -4,6 +4,7 @@ import { cache } from "react"; import { query } from "@/lib/db"; import { log } from "@/lib/log"; +import { CACHE_TTL_HOURS, questionKey } from "@/lib/question-key"; // Unguessable, URL-safe, 10 characters (60 bits): links are shareable but not enumerable. const newId = () => randomBytes(8).toString("base64url").slice(0, 10); @@ -11,10 +12,17 @@ const newId = () => randomBytes(8).toString("base64url").slice(0, 10); export type StoredAnswer = { id: string; question: string; result: unknown; createdAt: string }; // Best-effort: an answer that can't be stored is still shown, just without a share link. -export async function saveAnswer(question: string, result: unknown): Promise { +// `lectureId` is the session an Ask was scoped to (null = whole library), so reuse never crosses scopes. +export async function saveAnswer(question: string, result: unknown, lectureId: string | null = null): Promise { const id = newId(); try { - await query(`INSERT INTO answers (id, question, result) VALUES ($1, $2, $3)`, [id, question.slice(0, 300), JSON.stringify(result)]); + await query(`INSERT INTO answers (id, question, result, question_key, lecture_id) VALUES ($1, $2, $3, $4, $5)`, [ + id, + question.slice(0, 300), + JSON.stringify(result), + questionKey(question), + lectureId, + ]); return id; } catch (error) { log("answers.save_failed", { error: error instanceof Error ? error.message.slice(0, 120) : String(error) }); @@ -37,3 +45,25 @@ export async function recordFeedback(id: string, helpful: boolean): Promise 0; } + +// Answer reuse: the stored answer for the same question in the same scope, if it is recent AND no session has +// been added, published or changed since (a changed library could make the old citations wrong). Best-effort: +// any failure just means "no cached answer" and the question is answered normally. +export async function findCachedAnswer(question: string, lectureId: string | null): Promise<{ id: string; result: Record } | null> { + const key = questionKey(question); + if (!key) return null; + try { + const [row] = await query<{ id: string; result: Record }>( + `SELECT id, result FROM answers + WHERE question_key = $1 AND lecture_id IS NOT DISTINCT FROM $2::uuid + AND created_at > now() - make_interval(hours => $3) + AND created_at >= (SELECT coalesce(max(updated_at), 'epoch'::timestamptz) FROM lectures) + ORDER BY created_at DESC LIMIT 1`, + [key, lectureId, CACHE_TTL_HOURS], + ); + return row ?? null; + } catch (error) { + log("answers.cache_failed", { error: error instanceof Error ? error.message.slice(0, 120) : String(error) }); + return null; + } +} diff --git a/src/lib/language.ts b/src/lib/language.ts index 96e769c..e615193 100644 --- a/src/lib/language.ts +++ b/src/lib/language.ts @@ -30,3 +30,10 @@ export function answerLanguage(question: string): string | null { if (!needsTranslation(question)) return null; return SCRIPTS.find(([re]) => re.test(question))?.[1] ?? "the same language and script as the question"; } + +// Models sometimes end Indic sentences with the CJK full stop (。). Replace it with the script's own stop: +// the danda (।) for Devanagari, Bengali and Gurmukhi, a plain full stop for the others. +export function fixPunctuation(text: string, language: string | null): string { + if (!language || !text.includes("。")) return text; + return text.replaceAll("。", /Hindi|Bengali|Punjabi/.test(language) ? "।" : "."); +} diff --git a/src/lib/question-key.ts b/src/lib/question-key.ts new file mode 100644 index 0000000..d179689 --- /dev/null +++ b/src/lib/question-key.ts @@ -0,0 +1,12 @@ +// Two learners asking the same thing should share one stored answer, however they type it: case, spacing and a +// trailing "?" don't change a question. Pure, so it is unit-tested. +export const CACHE_TTL_HOURS = 24; + +export function questionKey(question: string): string { + return question + .normalize("NFKC") + .toLowerCase() + .replace(/\s+/g, " ") + .replace(/[\s?!.,;:।。؟]+$/u, "") // trailing ? ! . , ; : and the Devanagari, CJK and Arabic stops + .trim(); +} diff --git a/tests/unit/question-key.test.ts b/tests/unit/question-key.test.ts new file mode 100644 index 0000000..ecf28de --- /dev/null +++ b/tests/unit/question-key.test.ts @@ -0,0 +1,42 @@ +import { describe, expect, it } from "vitest"; + +import { fixPunctuation } from "@/lib/language"; +import { questionKey } from "@/lib/question-key"; + +describe("questionKey", () => { + it("treats case, spacing and a trailing question mark as the same question", () => { + const k = questionKey("What is momentum in gradient descent?"); + expect(questionKey("what is momentum in gradient descent")).toBe(k); + expect(questionKey(" What is MOMENTUM in gradient descent ?? ")).toBe(k); + expect(questionKey("What is momentum in gradient descent!")).toBe(k); + }); + + it("keeps different questions apart", () => { + expect(questionKey("What is momentum?")).not.toBe(questionKey("What is RMSProp?")); + expect(questionKey("learning rate too high")).not.toBe(questionKey("learning rate too low")); + }); + + it("strips the Devanagari danda and normalises compatibility characters", () => { + expect(questionKey("ओवरफिटिंग क्या है?")).toBe("ओवरफिटिंग क्या है"); + expect(questionKey("ओवरफिटिंग क्या है।")).toBe("ओवरफिटिंग क्या है"); + expect(questionKey("Overfitting?")).toBe("overfitting"); + }); + + it("returns an empty key for punctuation only", () => { + expect(questionKey(" ?? ")).toBe(""); + }); +}); + +describe("fixPunctuation", () => { + it("replaces the CJK full stop with the danda for Hindi, Bengali and Punjabi", () => { + expect(fixPunctuation("यह उत्तर है。और यह भी。", "Hindi (Devanagari script)")).toBe("यह उत्तर है।और यह भी।"); + expect(fixPunctuation("a。", "Bengali")).toBe("a।"); + expect(fixPunctuation("a。", "Punjabi (Gurmukhi script)")).toBe("a।"); + }); + + it("uses a plain full stop for other languages, and leaves clean text and English alone", () => { + expect(fixPunctuation("a。", "Tamil")).toBe("a."); + expect(fixPunctuation("Already fine.", "Tamil")).toBe("Already fine."); + expect(fixPunctuation("a。", null)).toBe("a。"); + }); +}); From cf2a3a499bb2ef92bdfe9c4462795cf2515cb09d Mon Sep 17 00:00:00 2001 From: im-rk Date: Sat, 3 Oct 2026 15:56:16 +0530 Subject: [PATCH 2/4] feat(voice): ask by voice in English or Hindi, and allow the microphone for our own pages --- docs/SECURITY.md | 2 +- next.config.ts | 11 +++- src/components/SearchBar.tsx | 7 +- src/components/VoiceButton.tsx | 115 +++++++++++++++++++++++++++++++++ src/lib/voice.ts | 58 +++++++++++++++++ tests/unit/voice.test.ts | 44 +++++++++++++ 6 files changed, 233 insertions(+), 4 deletions(-) create mode 100644 src/components/VoiceButton.tsx create mode 100644 src/lib/voice.ts create mode 100644 tests/unit/voice.test.ts diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 47640e5..0ec5b6c 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -81,4 +81,4 @@ Rights confirmation is required before upload (`rights_confirmed_at`), sessions ## HTTP Security Headers -Every response carries (`next.config.ts`): `Strict-Transport-Security` (2 years, subdomains, preload), `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`, `X-Frame-Options: DENY` plus `Content-Security-Policy: frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none'` (no clickjacking, no base-tag or plugin injection; the one exception is `/embed/*`, the sign-in-free Ask box an LMS frames, whose `frame-ancestors` is `https:` or the `EMBED_FRAME_ANCESTORS` list; see [`EMBED.md`](EMBED.md)), and a `Permissions-Policy` that turns off camera, microphone, geolocation, payment and USB. `X-Powered-By` is removed. A full script-source CSP is deliberately not set yet: the Cloudinary Video Player loads scripts, styles and HLS segments from several hosts, so that policy needs testing against every player feature first. +Every response carries (`next.config.ts`): `Strict-Transport-Security` (2 years, subdomains, preload), `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`, `X-Frame-Options: DENY` plus `Content-Security-Policy: frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none'` (no clickjacking, no base-tag or plugin injection; the one exception is `/embed/*`, the sign-in-free Ask box an LMS frames, whose `frame-ancestors` is `https:` or the `EMBED_FRAME_ANCESTORS` list; see [`EMBED.md`](EMBED.md)), and a `Permissions-Policy` that turns off camera, geolocation, payment and USB and allows the microphone for Pravaha's own pages only (the voice question: audio never reaches Pravaha, the browser turns it into text). `X-Powered-By` is removed. A full script-source CSP is deliberately not set yet: the Cloudinary Video Player loads scripts, styles and HLS segments from several hosts, so that policy needs testing against every player feature first. diff --git a/next.config.ts b/next.config.ts index 6a378b8..369bb95 100644 --- a/next.config.ts +++ b/next.config.ts @@ -7,7 +7,8 @@ const baseHeaders = [ { key: "Strict-Transport-Security", value: "max-age=63072000; includeSubDomains; preload" }, { key: "X-Content-Type-Options", value: "nosniff" }, { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" }, - { key: "Permissions-Policy", value: "camera=(), microphone=(), geolocation=(), payment=(), usb=()" }, + // microphone=(self): only Pravaha's own pages may ask for it, which the voice question needs (components/VoiceButton.tsx). + { key: "Permissions-Policy", value: "camera=(), microphone=(self), geolocation=(), payment=(), usb=()" }, ]; const policy = (ancestors: string) => `frame-ancestors ${ancestors}; base-uri 'self'; form-action 'self'; object-src 'none'`; @@ -31,6 +32,14 @@ const nextConfig: NextConfig = { { key: "Content-Security-Policy", value: policy("'none'") }, ], }, + // The service worker must always be re-fetched, so a fix to it reaches every device on the next visit. + { + source: "/sw.js", + headers: [ + { key: "Cache-Control", value: "no-cache, no-store, must-revalidate" }, + { key: "Service-Worker-Allowed", value: "/" }, + ], + }, { source: "/embed/:path*", headers: [{ key: "Content-Security-Policy", value: policy(embedAncestors) }] }, ]; }, diff --git a/src/components/SearchBar.tsx b/src/components/SearchBar.tsx index 471b8c4..515d266 100644 --- a/src/components/SearchBar.tsx +++ b/src/components/SearchBar.tsx @@ -1,3 +1,5 @@ +import { VoiceButton } from "@/components/VoiceButton"; + // A plain GET form: works before JavaScript loads, and every search is a shareable URL. export function SearchBar({ defaultValue = "", autoFocus = false }: { defaultValue?: string; autoFocus?: boolean }) { return ( @@ -15,11 +17,12 @@ export function SearchBar({ defaultValue = "", autoFocus = false }: { defaultVal maxLength={300} required placeholder="Ask a question…" - className="h-14 w-full rounded-2xl border border-border bg-surface pr-36 pl-5 text-base shadow-sm transition-shadow placeholder:text-muted focus:border-accent focus:shadow-[0_0_0_4px_color-mix(in_srgb,var(--accent)_15%,transparent)] focus:outline-none sm:pr-40" + className="h-14 w-full rounded-2xl border border-border bg-surface pr-44 pl-5 sm:pr-52 text-base shadow-sm transition-shadow placeholder:text-muted focus:border-accent focus:shadow-[0_0_0_4px_color-mix(in_srgb,var(--accent)_15%,transparent)] focus:outline-none" /> - + / + diff --git a/src/components/VoiceButton.tsx b/src/components/VoiceButton.tsx new file mode 100644 index 0000000..e9d9058 --- /dev/null +++ b/src/components/VoiceButton.tsx @@ -0,0 +1,115 @@ +"use client"; + +import { useEffect, useRef, useState, useSyncExternalStore } from "react"; + +import { isVoiceLang, recognitionCtor, transcriptOf, VOICE_LANGS, voiceErrorMessage, type Recognition, type VoiceLang } from "@/lib/voice"; + +const KEY = "pravaha-voice-lang"; + +function storedLang(): VoiceLang { + try { + const v = localStorage.getItem(KEY); + return isVoiceLang(v) ? v : "en-IN"; + } catch { + return "en-IN"; + } +} + +// Ask by voice: tap the microphone, say the question (English or Hindi), and it is asked. Hidden where the +// browser has no speech recognition (Firefox), so nobody sees a button that can't work. +export function VoiceButton({ inputId }: { inputId: string }) { + const supported = useSyncExternalStore( + () => () => {}, + () => recognitionCtor(window) !== null, + () => false, + ); + const [lang, setLang] = useState("en-IN"); + const [listening, setListening] = useState(false); + const [message, setMessage] = useState(null); + const recognition = useRef(null); + + useEffect(() => { + const frame = requestAnimationFrame(() => setLang(storedLang())); + return () => cancelAnimationFrame(frame); + }, []); + useEffect(() => () => recognition.current?.stop(), []); + + if (!supported) return null; + + function toggleLang() { + const next: VoiceLang = lang === "en-IN" ? "hi-IN" : "en-IN"; + setLang(next); + try { + localStorage.setItem(KEY, next); + } catch { + // Storage blocked: the choice still applies for this page view. + } + } + + function start() { + const Ctor = recognitionCtor(window); + const input = document.getElementById(inputId) as HTMLInputElement | null; + if (!Ctor || !input) return; + if (listening) return recognition.current?.stop(); + + const r = new Ctor(); + r.lang = lang; + r.interimResults = true; + r.continuous = false; + r.maxAlternatives = 1; + let heard = ""; + r.onresult = (e) => { + heard = transcriptOf(e.results); + input.value = heard; // shown as it is heard + }; + r.onerror = (e) => setMessage(voiceErrorMessage(e.error)); + r.onend = () => { + setListening(false); + // Ask what was heard; a too-short or empty result is left in the box for the learner to edit. + if (heard.length >= 2) input.form?.requestSubmit(); + }; + setMessage(null); + recognition.current = r; + try { + r.start(); + setListening(true); + } catch { + setMessage(voiceErrorMessage("other")); + } + } + + const current = VOICE_LANGS.find((l) => l.code === lang)!; + const other = VOICE_LANGS.find((l) => l.code !== lang)!; + return ( + <> +
+ + +
+

+ {listening ? `Listening in ${current.name}… say your question.` : message} +

+ + ); +} diff --git a/src/lib/voice.ts b/src/lib/voice.ts new file mode 100644 index 0000000..8f76f1b --- /dev/null +++ b/src/lib/voice.ts @@ -0,0 +1,58 @@ +// Voice question: the browser's own speech recognition (Web Speech API, free, on-device or the browser vendor's +// service) turns a spoken question into text, and the normal Ask takes it from there. No audio ever reaches +// Pravaha. English (India) and Hindi; the Ask pipeline already answers a Hindi question in Hindi. Pure +// helpers, so they are unit-tested; the microphone itself lives in src/components/VoiceButton.tsx. + +export const VOICE_LANGS = [ + { code: "en-IN", label: "EN", name: "English" }, + { code: "hi-IN", label: "हिं", name: "Hindi" }, +] as const; +export type VoiceLang = (typeof VOICE_LANGS)[number]["code"]; + +export const isVoiceLang = (v: unknown): v is VoiceLang => VOICE_LANGS.some((l) => l.code === v); + +// Just enough of the (still prefixed in Chrome and Safari) SpeechRecognition API for this feature. +export type Recognition = { + lang: string; + interimResults: boolean; + continuous: boolean; + maxAlternatives: number; + onresult: ((e: { results: ArrayLike & { isFinal: boolean }> }) => void) | null; + onerror: ((e: { error: string }) => void) | null; + onend: (() => void) | null; + start(): void; + stop(): void; +}; +export type RecognitionCtor = new () => Recognition; + +export function recognitionCtor(w: object): RecognitionCtor | null { + const speech = w as { SpeechRecognition?: unknown; webkitSpeechRecognition?: unknown }; + return ((speech.SpeechRecognition ?? speech.webkitSpeechRecognition) as RecognitionCtor | undefined) ?? null; +} + +// The words so far, from every result the recogniser has produced (interim ones included while it is still +// listening), with the whitespace tidied. +export function transcriptOf(results: ArrayLike>): string { + let text = ""; + for (let i = 0; i < results.length; i++) text += results[i]![0]?.transcript ?? ""; + return text.replace(/\s+/g, " ").trim(); +} + +// What to tell the learner for each recogniser error, in plain words; null = nothing worth saying. +export function voiceErrorMessage(code: string): string | null { + switch (code) { + case "not-allowed": + case "service-not-allowed": + return "Microphone access is blocked. Allow it in your browser's site settings, or type the question."; + case "no-speech": + return "I didn't hear anything. Tap the microphone and try again."; + case "audio-capture": + return "No microphone was found."; + case "network": + return "Voice needs an internet connection. Type the question instead."; + case "aborted": + return null; + default: + return "Voice didn't work this time. Type the question instead."; + } +} diff --git a/tests/unit/voice.test.ts b/tests/unit/voice.test.ts new file mode 100644 index 0000000..0396b87 --- /dev/null +++ b/tests/unit/voice.test.ts @@ -0,0 +1,44 @@ +import { describe, expect, it } from "vitest"; + +import { isVoiceLang, recognitionCtor, transcriptOf, VOICE_LANGS, voiceErrorMessage } from "@/lib/voice"; + +const result = (transcript: string) => [{ transcript }]; + +describe("transcriptOf", () => { + it("joins every result so far and tidies whitespace", () => { + expect(transcriptOf([result("what is "), result("momentum")])).toBe("what is momentum"); + expect(transcriptOf([result(" overfitting क्या है ")])).toBe("overfitting क्या है"); + }); + + it("is empty before anything is heard", () => { + expect(transcriptOf([])).toBe(""); + expect(transcriptOf([[]])).toBe(""); + }); +}); + +describe("recognitionCtor", () => { + class Fake {} + it("finds the standard or the webkit-prefixed constructor, or none", () => { + expect(recognitionCtor({ SpeechRecognition: Fake })).toBe(Fake); + expect(recognitionCtor({ webkitSpeechRecognition: Fake })).toBe(Fake); + expect(recognitionCtor({})).toBeNull(); + }); +}); + +describe("voice languages and errors", () => { + it("offers English (India) and Hindi", () => { + expect(VOICE_LANGS.map((l) => l.code)).toEqual(["en-IN", "hi-IN"]); + expect(isVoiceLang("hi-IN")).toBe(true); + expect(isVoiceLang("fr-FR")).toBe(false); + expect(isVoiceLang(null)).toBe(false); + }); + + it("explains each failure in plain words, and stays quiet when the learner stopped it", () => { + expect(voiceErrorMessage("not-allowed")).toMatch(/blocked/i); + expect(voiceErrorMessage("no-speech")).toMatch(/didn't hear/i); + expect(voiceErrorMessage("audio-capture")).toMatch(/no microphone/i); + expect(voiceErrorMessage("network")).toMatch(/internet/i); + expect(voiceErrorMessage("anything-else")).toMatch(/didn't work/i); + expect(voiceErrorMessage("aborted")).toBeNull(); + }); +}); From 855a046168d9373e269e0c667dedec0545ffa16a Mon Sep 17 00:00:00 2001 From: im-rk Date: Sat, 3 Oct 2026 15:56:16 +0530 Subject: [PATCH 3/4] feat(pwa): installable app with icons, shortcuts and an offline page, plus e2e fixes --- public/sw.js | 23 +++++++++++ src/app/layout.tsx | 5 +++ src/app/manifest.ts | 27 +++++++++++++ src/app/offline/page.tsx | 23 +++++++++++ src/app/pwa-icon/[size]/route.tsx | 31 +++++++++++++++ src/components/ServiceWorker.tsx | 13 +++++++ tests/e2e/smoke.spec.ts | 15 +++++++- tests/e2e/voice-pwa.spec.ts | 64 +++++++++++++++++++++++++++++++ 8 files changed, 199 insertions(+), 2 deletions(-) create mode 100644 public/sw.js create mode 100644 src/app/manifest.ts create mode 100644 src/app/offline/page.tsx create mode 100644 src/app/pwa-icon/[size]/route.tsx create mode 100644 src/components/ServiceWorker.tsx create mode 100644 tests/e2e/voice-pwa.spec.ts diff --git a/public/sw.js b/public/sw.js new file mode 100644 index 0000000..8bcf0f7 --- /dev/null +++ b/public/sw.js @@ -0,0 +1,23 @@ +// Pravaha's service worker, deliberately tiny: it makes the app installable and gives a friendly page when a +// navigation fails because the device is offline. It caches ONE page (/offline) and nothing else: no scripts, +// no API responses, no video, so a deploy can never leave anyone on stale code. +const CACHE = "pravaha-offline-v1"; +const OFFLINE_URL = "/offline"; + +self.addEventListener("install", (event) => { + event.waitUntil(caches.open(CACHE).then((cache) => cache.add(new Request(OFFLINE_URL, { cache: "reload" })))); + self.skipWaiting(); +}); + +self.addEventListener("activate", (event) => { + event.waitUntil( + caches.keys().then((keys) => Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k)))).then(() => self.clients.claim()), + ); +}); + +self.addEventListener("fetch", (event) => { + if (event.request.mode !== "navigate") return; // everything else goes straight to the network + event.respondWith( + fetch(event.request).catch(async () => (await caches.match(OFFLINE_URL)) ?? Response.error()), + ); +}); diff --git a/src/app/layout.tsx b/src/app/layout.tsx index 4f8f9ba..69d0b4a 100644 --- a/src/app/layout.tsx +++ b/src/app/layout.tsx @@ -4,6 +4,7 @@ import Link from "next/link"; import { DataSaverToggle } from "@/components/DataSaverToggle"; import { LogoMark } from "@/components/Logo"; +import { ServiceWorker } from "@/components/ServiceWorker"; import { SearchShortcut } from "@/components/SearchShortcut"; import { SiteChrome } from "@/components/SiteChrome"; import { THEME_INIT_SCRIPT, ThemeToggle } from "@/components/ThemeToggle"; @@ -23,6 +24,9 @@ export const metadata: Metadata = { metadataBase: new URL(appUrl), title: "Pravaha — ask your recordings, watch the answer", description, + applicationName: "Pravaha", + appleWebApp: { capable: true, title: "Pravaha", statusBarStyle: "default" }, + icons: { apple: "/pwa-icon/192" }, openGraph: { siteName: "Pravaha", type: "website", title: "Pravaha — ask your recordings, watch the answer", description }, }; @@ -44,6 +48,7 @@ export default function RootLayout({ children }: { children: React.ReactNode }) Skip to content +
{/* Phone: logo and the two switches on the first row, the page links on a second row that scrolls if it must. diff --git a/src/app/manifest.ts b/src/app/manifest.ts new file mode 100644 index 0000000..e541699 --- /dev/null +++ b/src/app/manifest.ts @@ -0,0 +1,27 @@ +import type { MetadataRoute } from "next"; + +// Makes Pravaha installable: "Add to Home screen" on a phone opens it full-screen like an app. +export default function manifest(): MetadataRoute.Manifest { + return { + name: "Pravaha: ask your recordings, watch the answer", + short_name: "Pravaha", + description: "Ask your lecture recordings a question and watch the answer: a clip of the moment it was said.", + start_url: "/", + scope: "/", + display: "standalone", + orientation: "portrait", + background_color: "#fafaf7", + theme_color: "#0f766e", + categories: ["education"], + icons: [ + { src: "/pwa-icon/192", sizes: "192x192", type: "image/png", purpose: "any" }, + { src: "/pwa-icon/512", sizes: "512x512", type: "image/png", purpose: "any" }, + { src: "/pwa-icon/maskable-512", sizes: "512x512", type: "image/png", purpose: "maskable" }, + ], + shortcuts: [ + { name: "Ask a question", url: "/", description: "Ask your recordings" }, + { name: "Learn a topic", url: "/learn", description: "A short course from your lectures" }, + { name: "Saved", url: "/saved", description: "Weak spots and saved moments" }, + ], + }; +} diff --git a/src/app/offline/page.tsx b/src/app/offline/page.tsx new file mode 100644 index 0000000..f6f8b1b --- /dev/null +++ b/src/app/offline/page.tsx @@ -0,0 +1,23 @@ +import type { Metadata } from "next"; + +export const metadata: Metadata = { + title: "You're offline — Pravaha", + robots: { index: false, follow: false }, +}; + +// Served by the service worker (public/sw.js) when a page can't be fetched because the device is offline. +export default function OfflinePage() { + return ( +
+

+ 📡 +

+

You're offline

+

+ Pravaha needs a connection to play lectures and answer questions. Your saved moments and weak spots are kept on this device, and + they'll be here when you reconnect. +

+

Tip: turn on Data saver in the header for slow connections.

+
+ ); +} diff --git a/src/app/pwa-icon/[size]/route.tsx b/src/app/pwa-icon/[size]/route.tsx new file mode 100644 index 0000000..2052041 --- /dev/null +++ b/src/app/pwa-icon/[size]/route.tsx @@ -0,0 +1,31 @@ +import { ImageResponse } from "next/og"; + +// The app icon as a PNG at the sizes the web app manifest asks for (192, 512, and a maskable 512 with extra +// padding so Android's circular and squircle masks never crop the mark). Drawn from the same paths as +// app/icon.svg, so the installed icon matches the favicon. +const SIZES: Record = { + "192": { px: 192, maskable: false }, + "512": { px: 512, maskable: false }, + "maskable-512": { px: 512, maskable: true }, +}; + +export async function GET(_request: Request, { params }: { params: Promise<{ size: string }> }) { + const spec = SIZES[(await params).size]; + if (!spec) return new Response("Not found", { status: 404 }); + const { px, maskable } = spec; + // Maskable icons keep their art inside the central 80% (the "safe zone"); regular ones fill the tile. + const art = maskable ? px * 0.62 : px * 0.82; + + return new ImageResponse( + ( +
+ + + + + +
+ ), + { width: px, height: px, headers: { "Cache-Control": "public, max-age=31536000, immutable" } }, + ); +} diff --git a/src/components/ServiceWorker.tsx b/src/components/ServiceWorker.tsx new file mode 100644 index 0000000..3d77214 --- /dev/null +++ b/src/components/ServiceWorker.tsx @@ -0,0 +1,13 @@ +"use client"; + +import { useEffect } from "react"; + +// Registers the offline-page service worker (public/sw.js). Production only, so development never serves a +// cached shell, and any failure is ignored: the app works the same without it. +export function ServiceWorker() { + useEffect(() => { + if (process.env.NODE_ENV !== "production" || !("serviceWorker" in navigator)) return; + navigator.serviceWorker.register("/sw.js", { scope: "/" }).catch(() => {}); + }, []); + return null; +} diff --git a/tests/e2e/smoke.spec.ts b/tests/e2e/smoke.spec.ts index b63e409..47feb83 100644 --- a/tests/e2e/smoke.spec.ts +++ b/tests/e2e/smoke.spec.ts @@ -24,7 +24,7 @@ test("Find lands on the exact second", async ({ page }) => { test("Ask answers with at least one playable citation", async ({ page }) => { await page.goto(`/search?q=${encodeURIComponent(QUESTION)}`); const answer = page.getByRole("region", { name: /Answer from your library/i }); - await expect(answer.getByRole("button", { name: "Source 1" })).toBeVisible({ timeout: 30_000 }); + await expect(answer.getByRole("button", { name: "Source 1" }).first()).toBeVisible({ timeout: 30_000 }); await expect(answer.getByRole("link", { name: "Open full session" }).first()).toBeVisible(); }); @@ -34,7 +34,18 @@ test("Ask refuses questions the library doesn't cover", async ({ page }) => { }); test("organizer API rejects anonymous uploads", async ({ request }) => { - const res = await request.post("/api/upload-signature", { data: { paramsToSign: {} } }); + // Well-formed organizer-preset params (the route validates the shape first and answers 400 to malformed ones), + // from someone with no organizer cookie: it must refuse to sign. + const res = await request.post("/api/upload-signature", { + data: { + paramsToSign: { + timestamp: Math.floor(Date.now() / 1000), + upload_preset: "pravaha_signed", + public_id: "pravaha/6f1c2a52-8d4b-4c7e-9f21-0a5b3c1d2e4f", + source: "uw", + }, + }, + }); expect(res.status()).toBe(401); }); diff --git a/tests/e2e/voice-pwa.spec.ts b/tests/e2e/voice-pwa.spec.ts new file mode 100644 index 0000000..e82f9be --- /dev/null +++ b/tests/e2e/voice-pwa.spec.ts @@ -0,0 +1,64 @@ +import { expect, test } from "@playwright/test"; + +// Voice question, installability and the offline page (run against the deployed app, like smoke.spec.ts). + +test("a spoken question is asked, in the language chosen", async ({ page }) => { + // A simulated recogniser: says the question as soon as it is started. + await page.addInitScript(() => { + const Fake = class { + lang = ""; + onresult: ((e: unknown) => void) | null = null; + onend: (() => void) | null = null; + start() { + setTimeout(() => { + this.onresult?.({ results: [[{ transcript: "what is momentum in gradient descent" }]] }); + setTimeout(() => this.onend?.(), 150); + }, 300); + } + stop() { + this.onend?.(); + } + }; + Object.assign(window, { SpeechRecognition: Fake, webkitSpeechRecognition: Fake }); + }); + await page.goto("/"); + await page.getByRole("button", { name: /ask by voice in english/i }).click(); + await expect(page).toHaveURL(/\/search\?q=what\+is\+momentum/); + await expect(page.getByRole("region", { name: /Answer from your library/i })).toBeVisible({ timeout: 45_000 }); + + await page.goto("/"); + await page.getByRole("button", { name: /voice language: english/i }).click(); + await expect(page.getByRole("button", { name: /ask by voice in hindi/i })).toBeVisible(); +}); + +test("no voice button where the browser has no speech recognition", async ({ page }) => { + await page.addInitScript(() => { + Reflect.deleteProperty(window, "SpeechRecognition"); + Reflect.deleteProperty(window, "webkitSpeechRecognition"); + }); + await page.goto("/"); + await expect(page.getByRole("searchbox", { name: /Ask or search the library/i })).toBeVisible(); + await expect(page.getByRole("button", { name: /ask by voice/i })).toHaveCount(0); +}); + +test("the app is installable: manifest, icons, and a service worker that only serves the offline page", async ({ page, request }) => { + const manifest = await (await request.get("/manifest.webmanifest")).json(); + expect(manifest).toMatchObject({ short_name: "Pravaha", display: "standalone", start_url: "/" }); + for (const icon of manifest.icons as { src: string; type: string }[]) { + const res = await request.get(icon.src); + expect(res.status(), icon.src).toBe(200); + expect(res.headers()["content-type"]).toContain("image/png"); + } + const sw = await request.get("/sw.js"); + expect(sw.status()).toBe(200); + expect(sw.headers()["cache-control"]).toContain("no-cache"); + expect(await sw.text()).toContain('mode !== "navigate"'); + + await page.goto("/offline"); + await expect(page.getByRole("heading", { name: /You're offline/i })).toBeVisible(); +}); + +test("the microphone is allowed for Pravaha's own pages", async ({ request }) => { + const res = await request.get("/"); + expect(res.headers()["permissions-policy"]).toContain("microphone=(self)"); +}); From b6a2a34395be5e0862de06f2c4f4e0e3d64d406a Mon Sep 17 00:00:00 2001 From: im-rk Date: Sat, 3 Oct 2026 15:56:17 +0530 Subject: [PATCH 4/4] docs(phase-25): answer reuse, voice, installable app, API and changelog --- CHANGELOG.md | 6 +++++ README.md | 4 ++++ docs/API.md | 5 ++++ docs/DATABASE.md | 1 + docs/DEMO.md | 4 ++++ docs/IMPLEMENTATION_PLAN.md | 1 + docs/SUBMISSION_CHECKLIST.md | 1 + .../phases/PHASE-25-answer-cache-voice-pwa.md | 23 +++++++++++++++++++ 8 files changed, 45 insertions(+) create mode 100644 docs/phases/PHASE-25-answer-cache-voice-pwa.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 93a9d62..19276a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,9 @@ Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](ht ## [Unreleased] ### Added +- Answer reuse: an identical question returns the stored answer (no AI call, about 1 s) until a session changes or 24 hours pass; `pnpm prewarm` warms the demo (Phase 25) +- Voice question: a microphone in the Ask bar, English or Hindi, using the browser's speech recognition (Phase 25) +- Installable app: web app manifest, icons, shortcuts and an offline page (Phase 25) - Public status page `/status` and `GET /api/status`: live database, every AI model and Cloudinary credits, with warnings at 80% and 95% (Phase 24) - Business case (`docs/BUSINESS.md`, README) and one whole-system architecture diagram (Phase 24) - Weak spots on Saved: wrong quiz answers become a personal revision reel of the explanations you missed (Phase 22) @@ -15,6 +18,9 @@ Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](ht - Cloudinary asset index: tags and contextual metadata on each session's asset, synced from the Studio and read back with the Search API (Phase 19) ### Fixed +- The `Permissions-Policy` header blocked the microphone on every page; it now allows it for Pravaha's own pages (Phase 25) +- Hindi answers ended sentences with the Chinese full stop (。) instead of the danda (।) +- Smoke tests: the anonymous-upload check sends well-formed params, and the Ask check tolerates two "Source 1" buttons on mobile - `/search` (Find and Ask results) crashed with "Something went wrong" since the data saver release: `ResultCard` called a client hook without `"use client"`. Fixed, with a unit test that fails the build for any hook used outside a client file - Phone header: Studio, data saver and the theme switch were off-screen below ~560 px. Header, Studio and /try now fit 360 px (Phase 23) diff --git a/README.md b/README.md index c371e0c..78b8006 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,8 @@ Colleges, clubs and coaching institutes record hundreds of hours of lectures and | **Weak spots** | Quiz mistakes are remembered on your device and come back as **one Cloudinary reel of exactly the explanations you missed**, with the answer and the second to jump to. Get a question right and it leaves the list. | | **Study notes** | Every session has a study sheet at `/notes/[id]`: summary, key concepts, chapters and the quiz with answers, each point linked to its timestamp. Copy it as Markdown, download it, or save it as a PDF. | | **Revision reel** | On `/saved`, the latest saved moments from any sessions play as one labelled video: a revision reel for the night before an exam. | +| **Voice** | Tap the microphone in the Ask bar and say the question, in English or Hindi. The browser turns speech into text, so no audio reaches Pravaha. | +| **Installable** | Add Pravaha to a phone's home screen; it opens full-screen and shows a friendly page when offline. | | **Study Packs** | Every session gets a summary, key concepts, a quiz whose explanations **play the moment** the teacher explains it, and a "Session in 60 seconds" highlight reel. Pravaha generates them automatically from the transcript. | | **Moments** | One tap turns any cited clip into a vertical, AI-cropped, subtitled short for WhatsApp or Instagram, with its own share page and preview card. The short is just a Cloudinary URL; nothing is rendered. | | **Insights** | Organizers see what learners ask, the **knowledge gaps** the library can't answer yet (what to record next), and which Moments get shared. Every report downloads as CSV. Visitors can explore a read-only demo of the Studio. | @@ -223,6 +225,8 @@ Open the live app at **[pravaha-cyan.vercel.app](https://pravaha-cyan.vercel.app 8. Open **[Studio](https://pravaha-cyan.vercel.app/studio)**: a read-only demo of the organizer side, with every session's pipeline output and live Insights (knowledge gaps, most asked questions, answers rated helpful). Uploading to the main library and publishing need the organizer passcode at `/studio/sign-in`. 9. Open **[Status](https://pravaha-cyan.vercel.app/status)**: live database health, every AI model, and the Cloudinary credits the media runs on. +10. Tap the **microphone** in the Ask bar (Chrome or Safari) and ask by voice, or switch it to Hindi with the EN / हिं button. + ## Quick start **Prerequisites:** diff --git a/docs/API.md b/docs/API.md index c734024..42a4915 100644 --- a/docs/API.md +++ b/docs/API.md @@ -175,3 +175,8 @@ Retrieval now rewrites a question into the library's vocabulary when it is in an - **Auth:** public, `Cache-Control: no-store` - **Response:** `{ level: "operational"|"degraded"|"outage", reasons[], version, checkedAt, database: { ok, ms }, ai: { providers[], models: [{ model, ok, ms, kind? }] | null, probedAt }, cloudinary: { used, limit, pct, level, transformations, storage, bandwidth, reportedOn } | null, library: { sessions, moments, studyPacks, questionsAsked } | null }` - `503` only when the database is unreachable. AI probes are cached 5 minutes and Cloudinary usage 10 minutes per server instance. `kind` is `quota`, `overloaded` or `error`, never a raw provider message. No secrets or config values + +## Phase 25 additions + +### `POST /api/ask` (answer reuse) +An identical question (normalised: case, whitespace and trailing punctuation ignored) in the same scope (the whole library, or the same `lectureId`) is answered from the stored answer when it is under 24 hours old and no session has been added, published or changed since. The response is the stored one plus `"cached": true`, with the same `answerId`. No AI call is made and the rate limit still applies. diff --git a/docs/DATABASE.md b/docs/DATABASE.md index faaf5da..5cb6018 100644 --- a/docs/DATABASE.md +++ b/docs/DATABASE.md @@ -82,6 +82,7 @@ Transcripts can identify people. Logs reference `lectureId`, never transcript te | `003_study_packs_insights.sql` | `study_packs` (one validated pack per session), `ask_log` (question text + outcome, **no identity**), `moment_events` (anonymous open/share counts) | | `005_trials.sql` | `lectures.trial_expires_at`, `lectures.trial_ip_hash` (salted hash, rate limiting only) and a check that trials stay `unlisted`: public trial sessions from `/try`, deleted with their Cloudinary assets after expiry (`src/lib/trials.ts`) | | `004_shared_answers.sql` | `answers`: each answered Ask stored as shown (random 10-character id, question, result JSONB) for the share page `/a/[id]`, plus anonymous `helpful` / `unhelpful` counters. **No identity** | +| `007_answer_cache.sql` | `answers.question_key` (the normalised question) and `answers.lecture_id` (the session an Ask was scoped to, NULL for the whole library) plus an index, so an identical recent question can reuse its stored answer. Older rows have NULLs and are never matched | Applied with `pnpm db:migrate` (tracked in `schema_migrations`, each file once, in a transaction). diff --git a/docs/DEMO.md b/docs/DEMO.md index 06a7f26..e438435 100644 --- a/docs/DEMO.md +++ b/docs/DEMO.md @@ -28,6 +28,10 @@ Never show setup, code, dashboards or waiting. Every shot is the problem, the pr **Study shots (if there is time):** answer a quiz question wrong → `/saved` → **Play my weak-spot reel** ("What you get wrong comes back as video.") → a session’s **Study notes** → **Download .md** ("Every point links to the second the teacher said it.") +**Before recording:** run `APP_URL=https://pravaha-cyan.vercel.app pnpm prewarm` so every demo question answers instantly and every reel is already generated. + +**Voice shot (10 s):** tap the microphone and ask in Hindi ("The question is spoken, the answer comes back in Hindi.") + **Proof shot (10 s):** open `/status`: "The product watches itself: database, every AI model and the Cloudinary credits it runs on." **Bonus shot (if there is time):** header → **Data saver** on → the same answer reel and thumbnails reload visibly lighter. Voice-over: "Built for India’s mobile data: one switch, and Cloudinary serves everything at a fraction of the bytes." diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md index 42bd9d3..383b7cd 100644 --- a/docs/IMPLEMENTATION_PLAN.md +++ b/docs/IMPLEMENTATION_PLAN.md @@ -99,3 +99,4 @@ The core loop (Phases 01–09) is built and verified on real Cloudinary + Neon. | 20 | Judges page & revision reel | `/judges` maps the brief to Cloudinary capabilities with live URLs; saved moments replay as one reel | ✅ done (Oct 3) | | 23 | Phone layout | Header, Studio and /try fit a 360 px phone; e2e guard | ✅ done (Oct 3) | | 24 | Status page & business case | Live health, AI probes and Cloudinary credits at `/status`; who pays, unit economics and pricing hypothesis; whole-system diagram | ✅ done (Oct 3) | +| 25 | Answer reuse, voice questions, installable app | Identical questions reuse the stored answer (no AI call); ask by voice in English or Hindi; manifest, icons and an offline page; Hindi punctuation fix | ✅ done (Oct 3) | diff --git a/docs/SUBMISSION_CHECKLIST.md b/docs/SUBMISSION_CHECKLIST.md index 375e9ac..2a4f286 100644 --- a/docs/SUBMISSION_CHECKLIST.md +++ b/docs/SUBMISSION_CHECKLIST.md @@ -17,6 +17,7 @@ Deadline: submit by **Oct 3, 2026**; code freeze **Oct 4, 00:15 IST**. Submit vi - [x] Organizer and enterprise features merged and checked on Vercel previews (Oct 2–3): demo Studio, Insights charts and CSV export, LMS embed, Privacy and Terms, health endpoint - [x] Public status page `/status` shows live credits (warns at 80% and 95%), AI model health and database reachability (Phase 24) - [x] Business case for the Track 3 pitch: `docs/BUSINESS.md` and the README (Phase 24) +- [ ] Run `pnpm prewarm` against production shortly before judging and before recording the demo (answers are reused for 24 hours or until a session changes, so run it after the last publish) - [ ] **Cloudinary credits:** the Admin API reported 14.1 of 25 used (56%) at its last update (Oct 2). Every new reel, Moment and Compare Reel spends some, so avoid regenerating them in bulk before judging, and re-check `api.usage()` on submission day - [ ] Trials decision after that: keep `/try` paused (`TRIALS_PER_DAY=0`) or re-enable (`TRIALS_PER_DAY=5`, then redeploy) diff --git a/docs/phases/PHASE-25-answer-cache-voice-pwa.md b/docs/phases/PHASE-25-answer-cache-voice-pwa.md new file mode 100644 index 0000000..4cd4963 --- /dev/null +++ b/docs/phases/PHASE-25-answer-cache-voice-pwa.md @@ -0,0 +1,23 @@ +# Phase 25 — Answer reuse, voice questions, installable app + +**Status: DONE (Oct 3)** · branch `feature/answer-cache-voice-ask-pwa` + +## Why +Three things that decide whether a live demo and a real learner's phone work: judges will ask the *same* suggested questions (each one a fresh AI call against a free-tier quota), most learners hold a phone not a keyboard, and a web app that can't be installed feels like a website. + +## What shipped +1. **Answer reuse** (`migrations/007_answer_cache.sql`, `src/lib/answers.ts`, `src/lib/question-key.ts`): an identical question (case, spacing and a trailing "?" ignored) in the same scope returns the stored answer, with the same citations and share link, with **no retrieval and no AI call**. A repeat took about 1 s against about 12 s cold, and spends no Gemini or Groq quota. A reused answer expires after 24 hours and, more importantly, **whenever any session is added, published or changed** (`answers.created_at >= max(lectures.updated_at)`), so it can never cite a library that has since changed. A session-scoped Ask is never served to a library-wide one. Reused answers still count in Insights. Best-effort: any failure just means the question is answered normally. `pnpm prewarm` (`scripts/prewarm.mjs`) asks the demo questions and opens their reels so the first judge gets instant results; it stops if Cloudinary credits are above 90%. +2. **Voice question** (`src/components/VoiceButton.tsx`, `src/lib/voice.ts`): a microphone in the Ask bar, English (India) or Hindi, using the browser's own speech recognition. The words appear as they are heard and the question is asked when the speaker stops. Audio never reaches Pravaha. Hidden in browsers without speech recognition (Firefox). Plain-language messages for blocked microphone, silence, no microphone and no network. **The site's `Permissions-Policy` had `microphone=()`, which would have blocked it everywhere; it is now `microphone=(self)`.** +3. **Installable app** (`src/app/manifest.ts`, `src/app/pwa-icon/[size]/route.tsx`, `public/sw.js`, `/offline`): a web app manifest, 192 / 512 / maskable PNG icons drawn from the logo, shortcuts (Ask, Learn, Saved) and an offline page. The service worker is deliberately tiny: it caches **one page** (`/offline`) and answers only failed navigations. It caches no scripts, API responses or video, so a deploy can never leave anyone on stale code. Registered in production only. +4. **Hindi punctuation:** models sometimes ended Hindi sentences with the Chinese full stop (。). They now end with the danda (।) (Bengali and Punjabi too; a plain full stop for other scripts). + +## Decisions +- Reuse is keyed on the normalised question text, not on meaning. Two differently worded questions are two answers: a cheap, predictable rule beats an embedding lookup that could serve the wrong answer. +- The invalidation rule errs toward answering again: any lecture change anywhere clears the cache, which is rare in a demo and always safe. +- No push notifications and no asset caching in the service worker: the offline page is the whole job. + +## Verification +- 160 unit tests (12 new: question key, punctuation, voice helpers). +- Live against the real database: three phrasings of one question gave one answer id, 12.1 s then 1.4 s then 0.8 s. +- Real browser with a simulated recogniser: the spoken question reaches `/search?q=…` and an answer appears; the button is absent without speech support; the bar fits a 360 px phone. +- Manifest, all three icons (visually checked), `sw.js` headers and `/offline` verified.