Add blueprint for YouTube/TikTok transcriber & intelligence platform

.github/workflows/deploy-vercel.yml

@@ -0,0 +1,42 @@
+name: Deploy Algebra Quest to Vercel
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'algebra-quest/**'
+      - '.github/workflows/deploy-vercel.yml'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: algebra-quest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: algebra-quest/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build app
+        run: npm run build
+
+      - name: Deploy to Vercel
+        run: |
+          npx vercel pull --yes --environment=production --token="${{ secrets.VERCEL_TOKEN }}"
+          npx vercel build --prod --token="${{ secrets.VERCEL_TOKEN }}"
+          npx vercel deploy --prebuilt --prod --token="${{ secrets.VERCEL_TOKEN }}"
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

algebra-quest/.env.example

@@ -0,0 +1,2 @@
+# Server-side environment variables
+ANTHROPIC_API_KEY=your_anthropic_api_key_here

algebra-quest/DEPLOYMENT.md

@@ -0,0 +1,51 @@
+# Deployment Guide (Vercel)
+
+This app is configured to deploy on Vercel as a Vite frontend with a serverless API endpoint at `api/generate.js`.
+
+## 1) Prerequisites
+
+- Vercel account
+- Anthropic API key
+- This repository connected to GitHub
+
+## 2) Import project to Vercel
+
+1. In Vercel, click **Add New Project** and import this repo.
+2. Set the **Root Directory** to `algebra-quest`.
+3. Build settings should auto-detect from `vercel.json`:
+   - Build Command: `npm run build`
+   - Output Directory: `dist`
+
+## 3) Configure environment variables
+
+In Vercel project settings, add:
+
+- `ANTHROPIC_API_KEY` = your Anthropic API key
+
+## 4) First deploy
+
+- Click **Deploy** in Vercel, or push to `main`.
+- The app URL will be generated by Vercel.
+
+## 5) Optional CI/CD automation
+
+A GitHub Actions workflow is included at `.github/workflows/deploy-vercel.yml`.
+To enable automatic production deployment on pushes to `main`, configure these repository secrets:
+
+- `VERCEL_TOKEN`
+- `VERCEL_ORG_ID`
+- `VERCEL_PROJECT_ID`
+
+## 6) Verify deployment
+
+After deploy:
+
+1. Load the app home page.
+2. Start a lesson and generate a practice problem.
+3. Confirm the API route works by ensuring no `ANTHROPIC_API_KEY not configured` errors appear.
+
+## Troubleshooting
+
+- **500: `ANTHROPIC_API_KEY not configured`**: missing env var in Vercel.
+- **Build fails**: run `npm ci && npm run build` inside `algebra-quest` locally.
+- **API failures**: verify Anthropic key is valid and has quota.

youtube-tiktok-transcriber-blueprint.md

@@ -0,0 +1,287 @@
+# YouTube + TikTok Transcriber & Intelligence Platform Blueprint
+
+## Product Vision
+Build an AI-powered platform that does **far more than transcription**:
+
+1. **Accurate multimodal transcription** (speech + on-screen text + scene context)
+2. **Deep video intelligence** (framework extraction, argument mapping, sentiment and persuasion analysis)
+3. **Actionable outputs** (summaries, repurposing ideas, hooks, CTAs, content scorecards)
+4. **Quality controls** that make output more reliable than current one-click tools
+
+The goal is not just to convert audio to text, but to transform each video into a **structured intelligence asset**.
+
+---
+
+## Core User Jobs To Be Done
+
+### Primary jobs
+- "Give me a transcript I can trust, fast."
+- "Tell me the key insights without watching the full video."
+- "Extract frameworks, methods, and step-by-step systems from creators."
+- "Help me repurpose this content for X/LinkedIn/newsletters/shorts."
+
+### Secondary jobs
+- "Compare creators/videos by quality and strategy."
+- "Identify hooks and retention patterns to improve my own videos."
+- "Store and search a personal knowledge base across many videos."
+
+---
+
+## MVP Scope (First 6-8 Weeks)
+
+### Inputs
+- YouTube URL
+- TikTok URL
+- Optional uploaded video file
+
+### Outputs
+- Timecoded transcript
+- 1-paragraph and 1-page summaries
+- Key takeaways (bullet list)
+- Framework breakdown (steps, principles, assumptions)
+- Claims/evidence extraction
+- Action items + implementation checklist
+
+### Essential UX
+- Single "Analyze" workflow
+- Job progress indicator
+- Export to Markdown/PDF/JSON
+- Workspace history of analyzed videos
+
+---
+
+## Differentiation Strategy: "Better Than the Market"
+
+Most tools stop at transcript + shallow summary. Your advantage should come from:
+
+1. **Reliability Layer**
+   - Confidence scoring per transcript segment
+   - Source linking: every summary sentence mapped to transcript timestamps
+   - "Hallucination guard": statements without transcript evidence are flagged
+
+2. **Framework Intelligence Layer**
+   - Detect if content uses known frameworks (AIDA, PAS, JTBD, storytelling arcs, etc.)
+   - Auto-convert unstructured advice into reusable SOP/checklist formats
+   - Distinguish principles vs tactics vs examples
+
+3. **Creator Strategy Layer**
+   - Hook analysis (first 3-10 seconds)
+   - Rhetorical structure and persuasion pattern mapping
+   - CTA strategy classification
+   - Virality signals (pace, novelty, emotion triggers)
+
+4. **Repurposing Layer**
+   - Generate channel-specific assets:
+     - X thread
+     - LinkedIn post
+     - Newsletter outline
+     - Carousel script
+     - Short-form hooks
+
+---
+
+## High-Level System Architecture
+
+1. **Ingestion Service**
+   - Validate URL
+   - Fetch metadata (title, description, channel, duration)
+   - Download audio/video stream
+
+2. **Media Processing Pipeline**
+   - Audio extraction and normalization
+   - VAD (voice activity detection)
+   - Speaker diarization (if multi-speaker)
+   - OCR for on-screen text frames (sampled)
+
+3. **Transcription Engine**
+   - Use Whisper-large-v3 or equivalent
+   - Optional fallback to hosted ASR provider for speed/accuracy
+   - Store token-level timestamps and confidence where possible
+
+4. **Post-Processing Layer**
+   - Punctuation restoration
+   - Entity normalization (names, brands, terms)
+   - Segment transcript into semantic chunks
+
+5. **Analysis Engine (LLM + Rules)**
+   - Summarization chain (short + long + executive)
+   - Framework extraction chain
+   - Claims/evidence chain
+   - Improvement suggestions chain
+
+6. **Evidence Mapper**
+   - For each generated insight, attach supporting transcript spans
+   - Confidence score generation
+
+7. **Knowledge Store**
+   - SQL for metadata and jobs
+   - Object storage for media/artifacts
+   - Vector DB for semantic search across all videos
+
+8. **API + Frontend**
+   - Job submission/status/results endpoints
+   - Human-readable report page
+   - Searchable library and filters
+
+---
+
+## Recommended Tech Stack
+
+### Backend
+- **Python + FastAPI** (rapid AI integration)
+- **Celery or Dramatiq** for async processing jobs
+- **Redis** as queue/cache
+- **Postgres** for relational data
+- **S3-compatible storage** for media and exports
+
+### AI/ML
+- **Whisper (self-hosted or API)** for transcription
+- **Pyannote** for speaker diarization
+- **OpenCV/Tesseract or cloud OCR** for on-screen text
+- **LLM (GPT/Claude-compatible via abstraction layer)** for analysis
+- **Embeddings + pgvector or dedicated vector DB** for retrieval/search
+
+### Frontend
+- **Next.js** with server actions/API routes
+- Tailwind for fast UI iteration
+- Simple dashboard with job timeline + report viewer
+
+### Ops
+- Dockerized services
+- Background worker autoscaling
+- Observability: OpenTelemetry + structured logs
+
+---
+
+## Data Model (Minimal)
+
+- `videos`: id, source_type, source_url, title, author, duration, published_at
+- `analysis_jobs`: id, video_id, status, started_at, completed_at, error
+- `transcript_segments`: id, video_id, start_ts, end_ts, text, confidence, speaker
+- `insights`: id, video_id, insight_type, content, confidence
+- `insight_evidence`: id, insight_id, segment_id
+- `exports`: id, video_id, export_type, path
+
+---
+
+## Prompt/Analysis Design (Critical)
+
+Use multi-step pipelines instead of one giant prompt:
+
+1. **Content map step**
+   - Identify sections and topic shifts
+2. **Summary step**
+   - Produce short and deep summaries
+3. **Framework step**
+   - Extract explicit and implicit frameworks
+4. **Critical analysis step**
+   - Spot assumptions, gaps, contradictions
+5. **Improvement step**
+   - Suggest stronger structure, clearer examples, better CTA
+6. **Evidence verification step**
+   - Drop or flag unsupported claims
+
+Use strict JSON schemas for every step to ensure deterministic outputs.
+
+---
+
+## Quality Framework (How You Win)
+
+### Metrics to track
+- Word Error Rate (WER) for transcripts on sampled benchmark set
+- Summary factuality score (human-rated + automated checks)
+- Evidence coverage (% insights backed by transcript segments)
+- Time-to-first-result
+- User edits per report (lower is better)
+
+### QA loop
+- Human-in-the-loop review on random 5-10% jobs
+- Collect correction feedback in product UI
+- Use corrected examples as evaluation set and prompt tuning data
+
+---
+
+## Feature Roadmap
+
+### Phase 1: Foundation (MVP)
+- URL ingestion
+- Transcript + summaries
+- Basic framework extraction
+- Export + workspace
+
+### Phase 2: Intelligence
+- Evidence-linked insights
+- Hook/CTA/rhetoric analysis
+- Cross-video semantic search
+- "Ask questions about this video" chat
+
+### Phase 3: Moat
+- Creator benchmarking dashboard
+- Niche-specific analysis templates (marketing, education, finance)
+- Team collaboration and shared libraries
+- API for external integrations
+
+---
+
+## Security, Legal, and Compliance Notes
+
+- Respect platform terms and copyright constraints
+- Store only what users are authorized to analyze
+- Provide deletion controls and retention policy settings
+- Encrypt data at rest and in transit
+- Keep audit logs for enterprise users
+
+---
+
+## Build Plan (Concrete)
+
+### Week 1-2
+- Set up ingestion + async job pipeline
+- Implement transcription end-to-end
+- Save timecoded segments
+
+### Week 3-4
+- Implement summary + key-takeaway generation
+- Add report page + exports
+- Add basic retry/error handling
+
+### Week 5-6
+- Add framework extraction and evidence mapping
+- Add confidence scoring and unsupported-claim flags
+- Add semantic search across transcript chunks
+
+### Week 7-8
+- Add hook/CTA analysis
+- Add quality dashboards + benchmark scripts
+- Launch private beta with 10-20 users
+
+---
+
+## Example "Best-in-Class" Output Package Per Video
+
+1. Executive summary (5 bullets)
+2. Full narrative summary
+3. Framework breakdown:
+   - Framework name
+   - Steps
+   - Why it works
+   - Failure modes
+4. Key claims + evidence table
+5. Contrarian/weak points
+6. "How to apply this" checklist
+7. Repurposing assets for 3 platforms
+8. Transcript with chapter timestamps
+
+---
+
+## Immediate Next Actions
+
+1. Build a thin MVP focused on reliability + evidence linking.
+2. Instrument quality metrics from day one.
+3. Interview daily users weekly and prioritize reduction in editing work.
+4. Add advanced analysis only after transcript trust is consistently high.
+
+If you'd like, the next step is I can turn this into:
+- a full PRD,
+- a technical architecture diagram + endpoint spec,
+- and a day-by-day implementation sprint plan.