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
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](ht

## [Unreleased]

### Added
- Concept Map `/concepts` and Compare view `/concepts/[key]`: the same concept from every teacher as one Compare Reel (Phase 19)
- 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)

## [1.0.0] — 2026-10-03

The hackathon submission. Live at https://pravaha-cyan.vercel.app; PR numbers refer to `Monolithic-Dev/Pravaha`.
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,8 @@ Colleges, clubs and coaching institutes record hundreds of hours of lectures and
| **Find** | Search every session for what was *said* and land on the exact second. |
| **Ask** | Ask a question in plain language. The answer comes **only** from your recordings, and every claim links to a **playable clip** of the moment it came from. Progress streams live while it works, and the answer suggests follow-up questions. If the library doesn't cover a question, Pravaha says so instead of guessing. |
| **Answer Reels** | The moments an answer cites, from different speakers and sessions, stitched into one labelled video. |
| **Concept Map** | `/concepts` lines up every concept your lectures teach and how many different teachers explain it. Open one and hear the same idea from each lecturer, back to back, as one Cloudinary-spliced video, until one explanation clicks. |
| **Learning Paths** | `/learn`: type a topic and get a 3–5 step course, ordered basics first, drawn from moments across the library and edited into one 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. Every report downloads as CSV. Visitors can explore a read-only demo of the Studio. |
Expand Down
14 changes: 14 additions & 0 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,3 +146,17 @@ Adds `checks.aiLive.models[{ model, ok, ms, error? }]`, one tiny real call per m

### `POST /api/ask` (behaviour)
Retrieval now rewrites a question into the library's vocabulary when it is in another script or keyword retrieval is thin. The stream gains an `{ "type": "understanding" }` event, and `retrieved` carries `expanded: boolean`.

## Phase 19 additions

### `GET /api/concepts`
- **Auth:** public
- **Response:** `[{ key, name, sessions }]`: every concept the published library teaches, most-taught first

### `GET /api/concepts/[key]`
- **Auth:** public
- **Response:** `{ key, name, moments: [{ lectureId, title, speaker, startS, endS, text, related }] }` (up to 5, one per session; `related` is true for a session that teaches it without naming it a key concept) · `404` unknown key

### `POST /api/organizer/index` · `GET /api/organizer/index`
- **Auth:** organizer cookie (`401` otherwise) · `maxDuration` 60 s
- `POST` writes tags and contextual metadata onto every session's Cloudinary asset, then returns `{ synced, skipped, assets }` read back with the Search API. `GET` returns just `{ assets: [{ publicId, tags, context }] }`
1 change: 1 addition & 0 deletions docs/IMPLEMENTATION_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,3 +93,4 @@ The core loop (Phases 01–09) is built and verified on real Cloudinary + Neon.
**PR policy (team lead, Oct 1):** a PR is opened only once a feature branch carries **at least 20 changed files**, so related phases ship together (`GIT_WORKFLOW.md`).

| 18 | Query understanding, Learning Paths, AI reliability | Rewrite questions into the library's words (and translate them), honest near-miss answers, `/learn` micro-courses as one Cloudinary reel, circuit breaker + deep health | ✅ done (Oct 3) |
| 19 | Concept Map & Cloudinary asset index | Same concept, every teacher, as one Compare Reel; tags + contextual metadata on Cloudinary assets, read back with the Search API | ✅ done (Oct 3) |
24 changes: 24 additions & 0 deletions docs/phases/PHASE-19-concept-map-cloudinary-index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Phase 19 — Concept Map & Cloudinary Asset Index

**Status: DONE (Oct 3)** · branch `feature/concept-map-cloudinary-index`

## Why this phase exists
A learner who doesn't understand an idea from one lecturer usually doesn't need *more* material, they need the same idea *explained differently*. Libraries bury that: the explanation that would click is in another session, under another title. Pravaha already knows every session's key concepts (the Study Packs), so it can line them up.

The second half closes a gap with Cloudinary itself: until now Pravaha's knowledge lived only in Postgres, and the Cloudinary media library knew nothing about it.

## What shipped
1. **Concept Map** (`/concepts`, `src/lib/concept-map.ts`, `src/lib/concepts.ts`): every key concept from every published Study Pack, grouped across sessions by a normalised key (case, punctuation, plurals and word order ignored). Concepts taught by more than one lecturer come first. No extra AI call: it reads what the Study Packs already hold.
2. **Compare view** (`/concepts/[key]`, `ConceptView.tsx`): the moments the Study Packs point at, then the closest moment from any session that teaches the idea without listing it as a key concept (found with the same retrieval Ask uses). They are spliced into **one Compare Reel** with `fl_splice`, each clip labelled with its speaker, plus one card per explanation (thumbnail, quote, open session, share as Moment). Shared with its own Cloudinary share card; a link back into `/learn` turns the concept into a course.
3. **Cloudinary asset index** (`src/lib/cloudinary-index.ts`, `src/lib/asset-metadata.ts`): when a Study Pack is built, the session's Cloudinary asset is tagged (`pravaha`, `lang-en`, `concept-…`) and given contextual metadata (`title`, `speaker`, `language`, `concepts`, `moments`). The Studio's **Cloudinary asset index** panel (organizer) backfills every session and reads the result back with the **Search API** (`resource_type:video AND tags=pravaha`), proving the round trip.
4. `ReelPlayer` extracted so Learning Paths and Compare share one reel button.

## Decisions
- **No audio-only "Listen mode".** Tried and measured: Cloudinary rejects splicing mixed-size sources when the output is audio (`.mp3`/`.m4a`/`.aac`), because the frame resize is skipped. It would have needed a video render first, which defeats the point, so it was dropped.
- Concept keys sort tokens and stem a trailing `s`, so tags read `concept-influence-learning-rate`. Keys are stable identifiers, not display text.
- The Search API is organizer-only (it can return unlisted assets); public pages never expose it.

## Verification
- 11 new unit tests (`concept-map`, `asset-metadata`).
- Live: `/concepts/overfitting` → three teachers (IIT Kharagpur, IIT Madras, NPTEL TensorFlow), Compare Reel 200 `video/mp4` 1.8 MB / 46 s.
- Live: organizer sync wrote tags and context for every Study Pack; the Search API read them back.
32 changes: 32 additions & 0 deletions openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -460,3 +460,35 @@ paths:
'200': { description: 'CSV with a UTF-8 byte-order mark, as an attachment', content: { text/csv: { schema: { type: string } } } }
'400': { description: Unknown report, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
'401': { description: Not an organizer and the demo Studio is off }
/concepts:
get:
summary: The concept map, every concept the published library teaches
operationId: listConcepts
security: [{}]
responses:
'200': { description: Concepts, most-taught first, content: { application/json: { schema: { type: array, items: { type: object, properties: { key: { type: string }, name: { type: string }, sessions: { type: integer } } } } } } }
/concepts/{key}:
get:
summary: One concept and the moments, across sessions, that explain it
operationId: getConcept
security: [{}]
parameters:
- { name: key, in: path, required: true, schema: { type: string, pattern: '^[a-z0-9-]{1,80}$' } }
responses:
'200': { description: The concept and up to 5 moments, content: { application/json: { schema: { type: object } } } }
'404': { description: No such concept, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
/organizer/index:
post:
summary: Tag every session's Cloudinary asset and read the tags back with the Search API
operationId: syncCloudinaryIndex
security: [{ organizerCookie: [] }]
responses:
'200': { description: Sync result, content: { application/json: { schema: { type: object } } } }
'401': { description: Not an organizer }
get:
summary: The tagged assets, from Cloudinary's Search API
operationId: listCloudinaryIndex
security: [{ organizerCookie: [] }]
responses:
'200': { description: Assets with tags and contextual metadata, content: { application/json: { schema: { type: object } } } }
'401': { description: Not an organizer }
28 changes: 28 additions & 0 deletions src/app/api/concepts/[key]/route.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
import { NextResponse } from "next/server";

import { getConcept } from "@/lib/concepts";
import { apiError } from "@/lib/http";

export const dynamic = "force-dynamic";

type Props = { params: Promise<{ key: string }> };

// One concept and the moments, across sessions, that explain it.
export async function GET(_request: Request, { params }: Props) {
const { key } = await params;
const concept = /^[a-z0-9-]{1,80}$/.test(key) ? await getConcept(key) : null;
if (!concept) return apiError(404, "not_found", "No such concept.");
return NextResponse.json({
key: concept.key,
name: concept.name,
moments: concept.moments.map((m) => ({
lectureId: m.lectureId,
title: m.title,
speaker: m.speaker,
startS: m.startS,
endS: m.endS,
text: m.text,
related: m.related,
})),
});
}
11 changes: 11 additions & 0 deletions src/app/api/concepts/route.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
import { NextResponse } from "next/server";

import { listConcepts } from "@/lib/concepts";

export const dynamic = "force-dynamic";

// The concept map: every concept the published library teaches and how many sessions explain it.
export async function GET() {
const concepts = await listConcepts();
return NextResponse.json(concepts.map((c) => ({ key: c.key, name: c.name, sessions: c.entries.length })));
}
21 changes: 21 additions & 0 deletions src/app/api/organizer/index/route.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
import { NextResponse } from "next/server";

import { isOrganizer } from "@/lib/auth";
import { searchAssets, syncAllAssets } from "@/lib/cloudinary-index";
import { unauthorized } from "@/lib/http";

export const maxDuration = 60;
export const dynamic = "force-dynamic";

// Organizer: write tags and contextual metadata onto every session's Cloudinary asset, then read them back
// with Cloudinary's Search API, which proves the round trip.
export async function POST() {
if (!(await isOrganizer())) return unauthorized();
const result = await syncAllAssets();
return NextResponse.json({ ...result, assets: await searchAssets() });
}

export async function GET() {
if (!(await isOrganizer())) return unauthorized();
return NextResponse.json({ assets: await searchAssets() });
}
58 changes: 58 additions & 0 deletions src/app/concepts/[key]/page.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
import type { Metadata } from "next";
import Link from "next/link";
import { notFound } from "next/navigation";

import { ConceptView } from "@/components/ConceptView";
import { UnderTheHood } from "@/components/UnderTheHood";
import { getConcept } from "@/lib/concepts";
import { conceptHoodItems } from "@/lib/hood-items";
import { SHARE_CARD, shareCardUrl } from "@/lib/media";

export const dynamic = "force-dynamic";

type Props = { params: Promise<{ key: string }> };

const validKey = (key: string) => /^[a-z0-9-]{1,80}$/.test(key);

export async function generateMetadata({ params }: Props): Promise<Metadata> {
const { key } = await params;
const concept = validKey(key) ? await getConcept(key) : null;
const first = concept?.moments[0];
if (!concept || !first) return { title: "Concept not found — Pravaha" };
const description = `${concept.name}, explained by ${concept.moments.length} moments from the lecture library, back to back.`;
const image = shareCardUrl(first.publicId, first.startS, { title: concept.name, subtitle: `Concept map · ${concept.moments.length} explanations` });
return {
title: `${concept.name} — Pravaha`,
description,
openGraph: { type: "article", siteName: "Pravaha", title: concept.name, description, url: `/concepts/${key}`, images: [{ url: image, ...SHARE_CARD, alt: concept.name }] },
twitter: { card: "summary_large_image", title: concept.name, description, images: [image] },
};
}

export default async function ConceptPage({ params }: Props) {
const { key } = await params;
const concept = validKey(key) ? await getConcept(key) : null;
if (!concept || concept.moments.length === 0) notFound();
return (
<div className="mx-auto mt-6 max-w-4xl">
<p className="text-sm">
<Link href="/concepts" className="text-muted hover:text-fg">
← Concept map
</Link>
</p>
<h1 className="mt-2 text-3xl font-semibold tracking-tight sm:text-4xl">{concept.name}</h1>
<p className="mt-2 text-muted">
{concept.moments.length} explanation{concept.moments.length === 1 ? "" : "s"} from your library
{concept.taughtBy > 1 ? `, ${concept.taughtBy} of them named by the sessions' own Study Packs` : ""}.
</p>
<ConceptView concept={concept} />
<UnderTheHood items={conceptHoodItems(concept.key, concept.moments)} />
<p className="mt-8 text-sm text-muted">
Want a guided order, basics first?{" "}
<Link href={`/learn?topic=${encodeURIComponent(concept.name)}`} className="font-medium text-accent hover:underline">
Turn {concept.name} into a short course →
</Link>
</p>
</div>
);
}
74 changes: 74 additions & 0 deletions src/app/concepts/page.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
import type { Metadata } from "next";
import Link from "next/link";

import { listConcepts } from "@/lib/concepts";

export const dynamic = "force-dynamic";

export const metadata: Metadata = {
title: "Concept map — Pravaha",
description: "Every concept your lectures teach, and how many different teachers explain each one. Hear them back to back.",
};

export default async function ConceptsPage() {
const concepts = await listConcepts();
const shared = concepts.filter((c) => c.entries.length > 1);
const single = concepts.filter((c) => c.entries.length === 1);
return (
<div className="mx-auto mt-6 max-w-4xl">
<h1 className="text-3xl font-semibold tracking-tight sm:text-4xl">
One idea, <span className="text-accent">every teacher.</span>
</h1>
<p className="mt-3 max-w-2xl text-muted">
Pravaha reads every session and maps the concepts it teaches. Open one to hear the same idea from each lecturer in your
library, edited by Cloudinary into one video, until one explanation clicks.
</p>

{concepts.length === 0 && (
<p className="mt-8 rounded-2xl border border-border bg-surface p-5 text-sm">
No concepts yet: they appear once sessions are published with a Study Pack.
</p>
)}

{shared.length > 0 && (
<section className="mt-8" aria-labelledby="shared">
<h2 id="shared" className="text-sm font-semibold tracking-wide text-muted uppercase">
Taught by more than one lecturer
</h2>
<ul className="mt-3 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
{shared.map((c) => (
<li key={c.key}>
<Link
href={`/concepts/${c.key}`}
className="flex h-full items-center justify-between gap-3 rounded-2xl border border-accent/40 bg-accent/5 p-4 hover:bg-accent/10"
>
<span className="font-medium">{c.name}</span>
<span className="tabular shrink-0 rounded-full bg-accent px-2.5 py-0.5 text-xs font-semibold text-accent-fg">
{c.entries.length} sessions
</span>
</Link>
</li>
))}
</ul>
</section>
)}

{single.length > 0 && (
<section className="mt-8" aria-labelledby="single">
<h2 id="single" className="text-sm font-semibold tracking-wide text-muted uppercase">
More concepts
</h2>
<ul className="mt-3 flex flex-wrap gap-2">
{single.map((c) => (
<li key={c.key}>
<Link href={`/concepts/${c.key}`} className="inline-block rounded-full border border-border bg-surface px-3 py-1.5 text-sm hover:border-accent">
{c.name}
</Link>
</li>
))}
</ul>
</section>
)}
</div>
);
}
3 changes: 3 additions & 0 deletions src/app/layout.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,9 @@ export default function RootLayout({ children }: { children: React.ReactNode })
<Link href="/learn" className="rounded-lg px-3 py-2 text-muted hover:bg-surface hover:text-fg">
Learn
</Link>
<Link href="/concepts" className="rounded-lg px-3 py-2 text-muted hover:bg-surface hover:text-fg">
Concepts
</Link>
<Link href="/saved" className="rounded-lg px-3 py-2 text-muted hover:bg-surface hover:text-fg">
Saved
</Link>
Expand Down
2 changes: 2 additions & 0 deletions src/app/sitemap.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
});
return [
{ url: base, changeFrequency: "daily", priority: 1 },
{ url: `${base}/learn`, changeFrequency: "monthly", priority: 0.6 },
{ url: `${base}/concepts`, changeFrequency: "weekly", priority: 0.7 },
{ url: `${base}/try`, changeFrequency: "monthly", priority: 0.6 },
{ url: `${base}/privacy`, changeFrequency: "yearly", priority: 0.2 },
{ url: `${base}/terms`, changeFrequency: "yearly", priority: 0.2 },
Expand Down
Loading
Loading