diff --git a/CHANGELOG.md b/CHANGELOG.md index 402fd6d..ed3809c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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`. diff --git a/README.md b/README.md index 23f252a..50ccce9 100644 --- a/README.md +++ b/README.md @@ -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. | diff --git a/docs/API.md b/docs/API.md index 06d8951..ff04f4a 100644 --- a/docs/API.md +++ b/docs/API.md @@ -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 }] }` diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md index a0d5ab7..63a19de 100644 --- a/docs/IMPLEMENTATION_PLAN.md +++ b/docs/IMPLEMENTATION_PLAN.md @@ -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) | diff --git a/docs/phases/PHASE-19-concept-map-cloudinary-index.md b/docs/phases/PHASE-19-concept-map-cloudinary-index.md new file mode 100644 index 0000000..eb4d89f --- /dev/null +++ b/docs/phases/PHASE-19-concept-map-cloudinary-index.md @@ -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. diff --git a/openapi.yaml b/openapi.yaml index 834ad27..2061082 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -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 } diff --git a/src/app/api/concepts/[key]/route.ts b/src/app/api/concepts/[key]/route.ts new file mode 100644 index 0000000..896b853 --- /dev/null +++ b/src/app/api/concepts/[key]/route.ts @@ -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, + })), + }); +} diff --git a/src/app/api/concepts/route.ts b/src/app/api/concepts/route.ts new file mode 100644 index 0000000..d80f55a --- /dev/null +++ b/src/app/api/concepts/route.ts @@ -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 }))); +} diff --git a/src/app/api/organizer/index/route.ts b/src/app/api/organizer/index/route.ts new file mode 100644 index 0000000..550e967 --- /dev/null +++ b/src/app/api/organizer/index/route.ts @@ -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() }); +} diff --git a/src/app/concepts/[key]/page.tsx b/src/app/concepts/[key]/page.tsx new file mode 100644 index 0000000..9cd36ba --- /dev/null +++ b/src/app/concepts/[key]/page.tsx @@ -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 { + 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 ( +
+

+ + ← Concept map + +

+

{concept.name}

+

+ {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` : ""}. +

+ + +

+ Want a guided order, basics first?{" "} + + Turn {concept.name} into a short course → + +

+
+ ); +} diff --git a/src/app/concepts/page.tsx b/src/app/concepts/page.tsx new file mode 100644 index 0000000..5f5ad58 --- /dev/null +++ b/src/app/concepts/page.tsx @@ -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 ( +
+

+ One idea, every teacher. +

+

+ 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. +

+ + {concepts.length === 0 && ( +

+ No concepts yet: they appear once sessions are published with a Study Pack. +

+ )} + + {shared.length > 0 && ( +
+

+ Taught by more than one lecturer +

+
    + {shared.map((c) => ( +
  • + + {c.name} + + {c.entries.length} sessions + + +
  • + ))} +
+
+ )} + + {single.length > 0 && ( +
+

+ More concepts +

+
    + {single.map((c) => ( +
  • + + {c.name} + +
  • + ))} +
+
+ )} +
+ ); +} diff --git a/src/app/layout.tsx b/src/app/layout.tsx index 92e694b..0ca2c0c 100644 --- a/src/app/layout.tsx +++ b/src/app/layout.tsx @@ -57,6 +57,9 @@ export default function RootLayout({ children }: { children: React.ReactNode }) Learn + + Concepts + Saved diff --git a/src/app/sitemap.ts b/src/app/sitemap.ts index cbf0400..76c4726 100644 --- a/src/app/sitemap.ts +++ b/src/app/sitemap.ts @@ -15,6 +15,8 @@ export default async function sitemap(): Promise { }); 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 }, diff --git a/src/components/CloudinaryIndex.tsx b/src/components/CloudinaryIndex.tsx new file mode 100644 index 0000000..8703c4b --- /dev/null +++ b/src/components/CloudinaryIndex.tsx @@ -0,0 +1,63 @@ +"use client"; + +import { useState } from "react"; + +type Asset = { publicId: string; tags: string[]; context: Record }; + +// Organizer tool: writes each session's concepts, language and speaker onto its Cloudinary asset as tags and +// contextual metadata, then reads them back through Cloudinary's Search API (tags=pravaha). +export function CloudinaryIndex() { + const [state, setState] = useState<"idle" | "working" | "failed">("idle"); + const [assets, setAssets] = useState(null); + + async function sync() { + setState("working"); + const res = await fetch("/api/organizer/index", { method: "POST", headers: { "Content-Type": "application/json" } }); + if (!res.ok) return setState("failed"); + setAssets(((await res.json()) as { assets: Asset[] }).assets); + setState("idle"); + } + + return ( +
+
+
+

+ Cloudinary asset index +

+

Tag every session in Cloudinary with its concepts and details, then query them with the Search API.

+
+ +
+ {state === "failed" &&

Couldn't sync. Check that you're signed in as an organizer.

} + {assets && ( + <> +

+ Cloudinary's Search API found {assets.length} tagged {assets.length === 1 ? "asset" : "assets"}. +

+
    + {assets.map((a) => ( +
  • +

    {a.context.title ?? a.publicId}

    +

    + {a.tags.map((t) => ( + + {t} + + ))} +

    +
  • + ))} +
+ + )} +
+ ); +} diff --git a/src/components/ConceptView.tsx b/src/components/ConceptView.tsx new file mode 100644 index 0000000..193fcfc --- /dev/null +++ b/src/components/ConceptView.tsx @@ -0,0 +1,70 @@ +"use client"; + +import Image from "next/image"; +import Link from "next/link"; + +import { MomentButton } from "@/components/MomentButton"; +import { ReelPlayer } from "@/components/ReelPlayer"; +import type { ConceptView as Concept } from "@/lib/concepts"; +import { formatTime } from "@/lib/format"; +import { reelUrl, thumbUrl } from "@/lib/media"; + +const firstName = (speaker: string | null, title: string) => (speaker ?? title).split(",")[0]!.slice(0, 38); + +// One concept, every teacher: the same idea explained in different voices, as one Cloudinary-stitched +// video (each clip labelled with who is speaking) and as cards that open the full session. +export function ConceptView({ concept }: { concept: Concept }) { + const { moments } = concept; + const reel = reelUrl(moments.map((m, i) => ({ publicId: m.publicId, startS: m.startS, endS: m.endS, label: `${i + 1} · ${firstName(m.speaker, m.title)}` }))); + const teachers = new Set(moments.map((m) => m.speaker ?? m.lectureId)).size; + + return ( +
+ {reel && moments.length > 1 && ( + + )} +
    + {moments.map((m, i) => ( +
  1. + + {`${m.title}, + {i + 1} + {formatTime(m.startS)} + +

    {m.speaker ?? "Unknown speaker"}

    +

    {m.title}

    +

    “{m.text}”

    + {m.related &&

    Closest moment in this session: it teaches the idea without listing it as a key concept.

    } +
    + + Open full session + + +
    +
  2. + ))} +
+
+ ); +} diff --git a/src/components/LearningPathView.tsx b/src/components/LearningPathView.tsx index b0b450d..7a964d9 100644 --- a/src/components/LearningPathView.tsx +++ b/src/components/LearningPathView.tsx @@ -2,9 +2,9 @@ import Image from "next/image"; import Link from "next/link"; -import { useState } from "react"; import { MomentButton } from "@/components/MomentButton"; +import { ReelPlayer } from "@/components/ReelPlayer"; import { formatTime } from "@/lib/format"; import { thumbUrl } from "@/lib/media"; import type { LearningPath } from "@/lib/paths"; @@ -29,7 +29,14 @@ export function LearningPathView({ path }: { path: LearningPath }) { ) : null}

- {path.reel && } + {path.reel && ( + + )}
    {path.steps.map((step) => ( @@ -84,23 +91,3 @@ export function LearningPathView({ path }: { path: LearningPath }) { ); } - -function CourseReel({ url, steps, durationS }: { url: string; steps: number; durationS: number }) { - const [playing, setPlaying] = useState(false); - if (playing) return