Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 55 additions & 31 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,65 @@
# Changelog

Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](https://semver.org/). Each merged feature PR adds its own entry.
Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](https://semver.org/). Each merged feature PR adds its own entry under [Unreleased].

## [Unreleased]

### Added (v3)
- **Moment pages** `/m/[segmentId]`: shared Moments land on a branded page (vertical clip, quote, full session, Ask bar) instead of a bare `.mp4` (Phase 16)
- **Cloudinary share cards**: Open Graph images for Moments and sessions, generated by Cloudinary from the video frame (Phase 16)
- **Learner Insights**: knowledge gaps, most asked questions, Moments that travel (Phase 14)
- **Study Packs**: summary, concepts, clip-backed quiz, "Session in 60 seconds" reel (Phase 13)
- **Answer Reels**: every answer as one video stitched from cited moments across sessions (Phase 12)
- **Gemini AI layer** with a model fallback chain (Phase 11)
- Core loop, Phases 01–09: Studio upload, Watch, webhook ingest, Find, Library, Moments, grounded Ask, hardening
## [1.0.0] — 2026-10-03

### Deployed
- Production on Vercel at https://pravaha-cyan.vercel.app (functions in `cle1`, next to Neon `us-east-2`); Cloudinary notifications point at the live webhook
The hackathon submission. Live at https://pravaha-cyan.vercel.app; PR numbers refer to `Monolithic-Dev/Pravaha`.

### Fixed
- Dev scripts load `.env` when `.env.local` is absent
- `openapi.yaml` covers every v3 endpoint; current-state docs describe Gemini and timed `l_text` captions

### Planned (v2 — `docs/IMPLEMENTATION_PLAN.md`)
- Phase 01 — Cloudinary spike
- Phase 02 — App shell + deploy
- Phase 03 — Studio: organizer auth + upload
- Phase 04 — Watch page
- Phase 05 — Ingest: webhook → segments
- Phase 06 — Find
- Phase 07 — Library + Moments
- Phase 08 — Ask
- Phase 09 — Hardening
- Phase 10 — Ship
### Added

**Learners**
- **LMS embed:** `/embed/ask` puts Ask inside Moodle, Canvas or any course page, for the library or one session (`?session=`, `?theme=`). Studio copies the iframe code. See `docs/EMBED.md` (#25)
- **Ask this session** on the Watch page, including "what is this about?" questions, with follow-ups kept in scope (#10)
- **Follow-along transcript** and a chapters tab on the Watch page (#13)
- **Quiz result and retry**, plus a reel of the explanations you missed (#14)
- Back-to-back citations from one session merged into one answer card (#15)
- **AI hover previews** on library cards, from Cloudinary's `e_preview` (#18)
- **Hindi:** questions asked in Hindi answered from English lectures, and a Hindi subtitle track from Cloudinary's transcript translation (#6)
- **Shareable answers** at `/a/{id}`, answer actions and helpfulness feedback; **Saved** moments, recent questions and Continue watching (#8)
- Streaming Ask with live progress, answer reveal, citation previews and follow-up questions; a small motion system (#2)
- Animated hero with a self-playing Ask demo; light and dark themes; home suggestions from real Study Packs (#5)
- Startup landing sections: use cases, comparison, Cloudinary, pricing, FAQ (#8)

**Organizers**
- **Insights CSV export:** every report downloads in full, Excel-ready, with protection against CSV formula injection (#26)
- **Insights charts:** questions per day and the sessions answers come from (#16)
- **Read-only demo Studio** for visitors, and an organizer sign-in page (#10)
- **Public trials** at `/try`: Cloudinary keeps the first 60 s through its own upload preset, and trials are deleted after 24 h (#10). When trials are switched off, the page explains the pipeline instead (#19)
- **Cloudinary under the hood:** a panel that explains each delivery URL step by step, on sessions and answers (#12)

**Trust and operations**
- **Privacy** and **Terms** pages, plus a trust section on the landing page (#23)
- `GET /api/health` and structured `server.error` logs from `onRequestError` (#17)
- Baseline HTTP security headers, `robots.txt` and sitemap (#8)
- Groq fallback when every Gemini model fails (#7)
- Ask eval on the real library: 11/11 questions, 31/32 citations supported (#9)

**Earlier phases** (`docs/IMPLEMENTATION_PLAN.md`)
- Moment pages `/m/[segmentId]` and Cloudinary-generated share cards (Phase 16)
- Learner Insights: knowledge gaps, most asked questions, Moments that travel (Phase 14)
- Study Packs: summary, concepts, clip-backed quiz, "Session in 60 seconds" reel (Phase 13)
- Answer Reels: an answer as one video spliced from cited moments across sessions (Phase 12)
- Gemini AI layer with a model fallback chain (Phase 11)
- Core loop, Phases 01–09: Studio upload, Watch, webhook ingest, Find, Library, Moments, grounded Ask, hardening
- Repository scaffold, CI, conventions and the documentation set, including `docs/VISION.md` and the phase specs (Phase 00)

### Changed
- **v2 re-scope (Oct 1):** product reframed as "Ask your recordings. Watch the answer." — Watch · Find · Ask · Moments. Custom chapter algorithm replaced by Cloudinary `auto_chaptering`; Cloudinary Video Player replaces plain `<video>`; NextAuth/GitHub OAuth replaced by an organizer passcode; Upstash replaced by a Postgres rate-limit table; Claude scope moved from title cleanup/query normalization to grounded Ask. Rationale: `docs/STRATEGY_REVISIT.md` (Revisit 2), `docs/DECISIONS.md`.
- Local repository connected to the HackIndia team remote, history based on its initial commit.
- `/embed/*` is the only route that can be framed; every other page keeps `X-Frame-Options: DENY` (#25)
- The player streams the `hd_lean` ladder, halving video credits; uploads are capped at the free plan's 100 MB (#4)
- Ask allows 60 questions an hour per IP, up from 20 (#9)
- README: dark-mode screenshots, tech icon tiles, real-library screenshots and NPTEL credits (#3, #9, #21, #22, #24)
- **v2 re-scope (Oct 1):** reframed as "Ask your recordings. Watch the answer." Cloudinary `auto_chaptering` replaced the custom chapter algorithm, and the Cloudinary Video Player replaced `<video>`. An organizer passcode replaced OAuth, and a Postgres rate-limit table replaced Upstash. Rationale: `docs/STRATEGY_REVISIT.md`, `docs/DECISIONS.md`
- Moved to `Monolithic-Dev/Pravaha` (Oct 2)

### Added
- `docs/VISION.md`, `docs/GIT_WORKFLOW.md`, v2 phase specs (`docs/phases/PHASE-01-cloudinary-spike.md` … `PHASE-10-ship.md`).
- Repository scaffold, CI, conventions, full documentation set (Phase 00).
### Fixed
- Sessions play through a named HLS streaming profile; the title stays under the player (#1)
- Find shows the closest moments when no moment contains every word (#11)
- Demo Insights show Moments from published sessions only (#10)
- Player poster is preloaded (mobile LCP 6.0 s → 5.0 s); paused badge contrast (#20)
- Dev scripts load `.env` when `.env.local` is absent; `openapi.yaml` covers every endpoint

### Deployed
- Production on Vercel (functions in `cle1`, next to Neon `us-east-2`). Cloudinary notifications point at the live webhook. Six NPTEL sessions (CC BY-NC-SA) were ingested through the production pipeline
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Colleges, clubs and coaching institutes record hundreds of hours of lectures and
| **Answer Reels** | The moments an answer cites, from different speakers and sessions, stitched into one labelled video. |
| **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. Visitors can explore a read-only demo of the Studio. |
| **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. |
| **Embed** | Organizers copy one `<iframe>` from the Studio and put **Ask** inside Moodle, Canvas or any course page, for the whole library or one session. Only that route can be framed. See [`docs/EMBED.md`](docs/EMBED.md). |
| **Try it** | Anyone can upload a short video at `/try`, no account: Cloudinary keeps the first 60 seconds, transcribes and chapters it, and about 20 seconds later it has a Study Pack and an **Ask this session** box. Trials are private and deleted after 24 hours. |

Expand Down
29 changes: 16 additions & 13 deletions docs/DEMO.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Demo — Pravaha

Official limit: **2–4 minutes**. Target **2:45**. Recorded Day 3 evening after code freeze, on the deployed URL, with a real library of 5–8 sessions.
Official limit: **2–4 minutes**. Target **2:45**. Recorded on the deployed URL with the real library (6 NPTEL sessions).

## The One Wow Moment

Expand All @@ -14,22 +14,25 @@ Never show setup, code, dashboards or waiting. Every shot is the problem, the pr

| Time | Shot | Voice-over |
|---|---|---|
| 0:00–0:15 | A Drive folder of 40 untitled lecture recordings; scrubbing a 90-min video, lost | "Our campus records hundreds of hours of lectures and talks. Nobody rewatches them — you can't find anything inside a video." |
| 0:15–0:25 | Title card: **Pravaha — ask your recordings, watch the answer.** | "Pravaha turns every recording into knowledge you can search, ask, and share." |
| 0:25–0:50 | Studio: drag in a raw recording, rights checkbox, real upload progress → cut → "Ready" | "An organizer uploads a raw recording. Cloudinary transcribes it, chapters it and prepares adaptive streaming — no editing." |
| 0:50–1:10 | Watch page: chapters on the seek bar, subtitles, click a chapter | "Every session gets AI chapters and subtitles, streamed adaptively." |
| 1:10–1:30 | Home → type a phrase → results across three sessions → click → plays from that exact second | "Find searches what was *said* across the whole library and drops you on the exact second." |
| **1:30–2:05** | **Ask:** "How do I stop my model from overfitting?" → answer with [1][2][3] → tap [2] → the professor explains it mid-sentence. Then ask "Who won the IPL?" → "Not covered in this library." | "Ask answers only from your recordings — and every claim is a clip of the moment it came from. If it isn't in the library, Pravaha says so." |
| **2:00–2:05** | Tap **Watch the answer**: one video, three moments, two lecturers, each labelled | "And the whole answer plays as one video, edited by Cloudinary from three lectures in real time." |
| **2:05–2:25** | **Share as Moment** → vertical subtitled clip, speaker tracked → native share sheet on a real phone → plays in WhatsApp | "One tap turns that moment into a vertical short — trimmed, AI-cropped to the speaker, subtitled. It's not a render job; it's a Cloudinary URL." |
| 2:25–2:35 | DevTools → Slow 3G → playback continues at lower quality | "And it holds up on a weak connection." |
| 2:35–2:45 | Architecture strip: Cloudinary (transcription · chaptering · player · g_auto · transformations) + Pravaha (retrieval · grounded Ask · Moments) · team | "Cloudinary turns video into data. Pravaha turns data into answers you can watch. Code Blooded, Track 3." |
| 0:00–0:12 | A Drive folder of untitled lecture recordings; scrubbing a 90-min video, lost | "Our campus records hundreds of hours of lectures. Nobody rewatches them: you can't find anything inside a video." |
| 0:12–0:20 | Title card: **Pravaha — ask your recordings, watch the answer.** | "Pravaha turns every recording into knowledge you can search, ask and share." |
| 0:20–0:38 | Studio: drag in a raw recording, real upload progress → cut → "Ready", "Study Pack" | "An organizer uploads a raw recording. Cloudinary transcribes it, chapters it and prepares adaptive streaming. No editing." |
| 0:38–0:55 | Watch page: chapters tab, follow-along transcript highlighting as it plays, switch subtitles to Hindi | "Every session gets AI chapters, a transcript that follows along, and subtitles, in Hindi too." |
| 0:55–1:08 | Home → type a phrase → results across sessions → click → plays from that exact second | "Find searches what was *said* across the library and drops you on the exact second." |
| **1:08–1:38** | **Ask:** "How do I stop my model from overfitting?" → live progress → answer with [1][2][3] → tap [2] → the professor explains it mid-sentence. Then "Who won the IPL in 2024?" → "Not covered in this library." | "Ask answers only from your recordings, and every claim is a clip of the moment it came from. If it isn't in the library, Pravaha says so." |
| **1:38–1:48** | Tap **Watch the answer**: one video, moments from two lecturers, each labelled | "The whole answer plays as one video, edited by Cloudinary from several lectures, in real time." |
| **1:48–2:06** | **Share as Moment** → vertical subtitled clip, speaker tracked → share sheet on a real phone | "One tap turns that moment into a vertical short: trimmed, AI-cropped to the speaker, subtitled. It's not a render job; it's a Cloudinary URL." |
| 2:06–2:24 | Studio → Insights: the IPL question under **Knowledge gaps** → CSV ↓. Then **Embed** → paste into a course page → Ask works inside it | "Organizers see what learners ask and what the library can't answer yet, export it, and put Ask right inside their LMS." |
| 2:24–2:35 | **Cloudinary under the hood** panel on the answer: each URL step explained | "Every clip, reel and short is a Cloudinary transformation, and Pravaha shows exactly which." |
| 2:35–2:45 | Architecture strip: Cloudinary (transcription · chaptering · streaming · g_auto · e_preview · transformations) + Pravaha (retrieval · grounded Ask · Moments · Insights) · team | "Cloudinary turns video into data. Pravaha turns data into answers you can watch. Code Blooded, Track 3." |

## Pre-Recording Checklist

- Library: 5–8 public sessions, overlapping topics (so Ask cites across sessions), clear audio.
- **Cloudinary credits first** (free plan: 25 a month). Check usage before recording. New uploads, new answer clips, reels and Moments cost credits; already-generated URLs don't. If usage is near the limit, upgrade first. If you can't, film the upload shot from an existing recording, and ask only questions that have been asked before (their clips are cached).
- Library: the 6 public NPTEL sessions, which overlap so Ask cites across sessions.
- The demo questions are in `tests/eval/ask-questions.json` and pass `pnpm eval:ask` the same evening.
- Moments used in the video are pre-warmed (opened once) so they play instantly.
- Moments and the Answer Reel used in the video are pre-warmed (opened once) so they play instantly.
- An HTTPS page with the embed code ready for the LMS shot (any page that accepts HTML).
- Phone screen recording ready for the share shot.
- Backup: a full-take screen recording of the flow, in case the live demo during judging stalls.

Expand Down
6 changes: 5 additions & 1 deletion docs/SUBMISSION_CHECKLIST.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ Deadline: submit by **Oct 3, 2026**; code freeze **Oct 4, 00:15 IST**. Submit vi
- [x] Working product on a live URL: https://pravaha-cyan.vercel.app (Vercel, deploys from `main`)
- [x] Learner flows (Watch, Find, Ask, Moments) work without login (Oct 2: Playwright smoke tests 12/12 against production, desktop and mobile)
- [x] Demo library: 6 public sessions (NPTEL excerpts, CC BY-NC-SA, credited in the README), uploaded through the production pipeline on Oct 2
- [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
- [ ] **Cloudinary credits:** 24.3 of 25 used on Oct 3 (free plan). Upgrade, or confirm the reset date is before judging, so new answer clips and Moments keep generating
- [ ] Trials decision after that: keep `/try` paused (`TRIALS_PER_DAY=0`) or re-enable (`TRIALS_PER_DAY=5`, then redeploy)

## Repository
- [x] Public repo: `Monolithic-Dev/Pravaha` (own repo is allowed by HackIndia's FAQ)
Expand All @@ -23,7 +26,8 @@ Deadline: submit by **Oct 3, 2026**; code freeze **Oct 4, 00:15 IST**. Submit vi
- [x] No API keys or credentials anywhere in history — `git log -p | grep -iE "api_secret|sk-ant|postgres://|passcode"` returns only env-variable references (checked Oct 2)

## Demo
- [ ] 2–4 minute video recorded per `DEMO.md` (target 2:45), publicly viewable link
- [ ] 2–4 minute video recorded per `DEMO.md` (target 2:45), publicly viewable link (check credits first: see its pre-recording checklist)
- [ ] Demo video link added to the README
- [ ] LinkedIn post with the demo, tagging HackIndia, Cloudinary and Jen Looper

## Submission
Expand Down
Loading