{"id":48381024,"url":"https://github.com/jstarfilms/ai-powered_personalized_learning_assistant","last_synced_at":"2026-04-05T20:03:29.759Z","repository":{"id":340958141,"uuid":"1162985049","full_name":"JStaRFilms/AI-Powered_Personalized_Learning_Assistant","owner":"JStaRFilms","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-18T20:33:43.000Z","size":628,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-25T13:26:04.457Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JStaRFilms.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-20T23:44:49.000Z","updated_at":"2026-03-18T20:33:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JStaRFilms/AI-Powered_Personalized_Learning_Assistant","commit_stats":null,"previous_names":["jstarfilms/ai-powered_personalized_learning_assistant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JStaRFilms/AI-Powered_Personalized_Learning_Assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JStaRFilms%2FAI-Powered_Personalized_Learning_Assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JStaRFilms%2FAI-Powered_Personalized_Learning_Assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JStaRFilms%2FAI-Powered_Personalized_Learning_Assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JStaRFilms%2FAI-Powered_Personalized_Learning_Assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JStaRFilms","download_url":"https://codeload.github.com/JStaRFilms/AI-Powered_Personalized_Learning_Assistant/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JStaRFilms%2FAI-Powered_Personalized_Learning_Assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31448219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-05T20:03:26.186Z","updated_at":"2026-04-05T20:03:29.747Z","avatar_url":"https://github.com/JStaRFilms.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 AI-Powered Personalized Learning Assistant\n\nA modern, AI-driven tutoring application that helps students learn effectively using their own curriculum materials. The app uses **Retrieval-Augmented Generation (RAG)** to answer questions based on uploaded documents, with adaptive learning modes that adjust to each student's experience level.\n\n![Next.js](https://img.shields.io/badge/Next.js-16-black) ![TypeScript](https://img.shields.io/badge/TypeScript-5-blue) ![Prisma](https://img.shields.io/badge/Prisma-5-2D3748) ![License](https://img.shields.io/badge/License-MIT-green)\n\n---\n\n## 📋 Table of Contents\n\n1. [Features](#-features)\n2. [Tech Stack](#-tech-stack)\n3. [Prerequisites](#-prerequisites)\n4. [Quick Start Guide](#-quick-start-guide)\n5. [Environment Setup](#-environment-setup)\n6. [Database Setup](#-database-setup)\n7. [Running the Application](#-running-the-application)\n8. [Available Scripts](#-available-scripts)\n9. [Project Structure](#-project-structure)\n10. [API Keys Setup](#-api-keys-setup)\n11. [Deployment](#-deployment)\n12. [Troubleshooting](#-troubleshooting)\n13. [Support](#-support)\n\n---\n\n## ✨ Features\n\n- **📚 Document Upload**: Upload PDFs, text files, and other curriculum materials\n- **🤖 AI Tutor (Lumina)**: Adaptive AI tutor that answers questions from your materials\n- **🧠 RAG Pipeline**: Vector-based similarity search to find relevant context\n- **📊 Analytics Dashboard**: Track learning progress and usage statistics\n- **💬 Chat History**: Save and review past conversations\n- **⚙️ Customizable Settings**: Toggle Socratic method, curriculum strictness\n- **🔐 Authentication**: Secure email/password authentication via Better Auth\n- **📈 Usage Tracking**: Built-in token and API call limits\n\n---\n\n## 🛠 Tech Stack\n\n| Category | Technology |\n|----------|------------|\n| **Framework** | Next.js 16 (App Router) |\n| **Language** | TypeScript |\n| **Database** | PostgreSQL (Neon) |\n| **ORM** | Prisma |\n| **Authentication** | Better Auth |\n| **AI/ML** | OpenRouter SDK, Vercel AI SDK |\n| **Embeddings** | NVIDIA Nemotron (via OpenRouter) |\n| **Styling** | Tailwind CSS |\n| **UI Components** | Radix UI, Lucide Icons |\n| **PDF Processing** | pdf-parse |\n\n---\n\n## ✅ Prerequisites\n\nBefore setting up this project, ensure you have the following installed:\n\n### 1. Node.js\n\n**Required Version**: 18.x or higher\n\n```bash\n# Check if Node.js is installed\nnode --version\n\n# If not installed, download from: https://nodejs.org\n# Recommended: Use nvm (Node Version Manager)\n# Windows: https://github.com/coreybutler/nvm-windows\n# macOS/Linux: https://github.com/nvm-sh/nvm\n```\n\n### 2. Package Manager\n\nThis project uses **pnpm** for package management.\n\n```bash\n# Install pnpm globally\nnpm install -g pnpm\n\n# Verify installation\npnpm --version\n```\n\n### 3. Git\n\n```bash\n# Check if Git is installed\ngit --version\n```\n\n### 4. Database (Neon)\n\nYou need a **Neon PostgreSQL** account. Sign up for free at:\nhttps://neon.tech\n\n---\n\n## 🚀 Quick Start Guide\n\nFollow these steps to get the application running locally:\n\n### Step 1: Clone the Repository\n\n```bash\ngit clone \u003crepository-url\u003e\ncd 2026-02-20_AI-Powered_Personalized_Learning_Assistant\n```\n\n### Step 2: Install Dependencies\n\n```bash\n# Using pnpm (recommended)\npnpm install\n\n# Or using npm\nnpm install\n\n# Or using yarn\nyarn install\n```\n\n### Step 3: Environment Setup\n\n```bash\n# Copy the example environment file\ncp .env.example .env.local\n```\n\n### Step 4: Configure Environment Variables\n\nEdit `.env.local` and add your API keys. See the [Environment Setup](#-environment-setup) section for details.\n\n### Step 5: Database Setup\n\n```bash\n# Generate Prisma Client\npnpm prisma generate\n\n# Push schema to database\npnpm prisma db push\n```\n\n### Step 6: Run the Development Server\n\n```bash\npnpm dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) in your browser.\n\n---\n\n## 🔧 Environment Setup\n\n### Required Environment Variables\n\nCreate a `.env.local` file in the project root with the following variables:\n\n```env\n# =============================================================================\n# DATABASE CONFIGURATION (Neon PostgreSQL)\n# =============================================================================\n# Get these from your Neon project dashboard: https://neon.tech\n\nDATABASE_URL=\"postgresql://username:password@ep-xxx.us-east-1.aws.neon.tech/neondb?sslmode=require\"\nDATABASE_URL_UNPOOLED=\"postgresql://username:password@ep-xxx.us-east-1.aws.neon.tech/neondb?sslmode=require\u0026schema=public\"\n\n# =============================================================================\n# AUTHENTICATION (Better Auth)\n# =============================================================================\nBETTER_AUTH_SECRET=\"your-generated-secret-key-min-32-chars-here\"\nBETTER_AUTH_URL=\"http://localhost:3000\"\n\n# =============================================================================\n# AI PROVIDERS (OpenRouter)\n# =============================================================================\nOPENROUTER_API_KEY=\"sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n\n# =============================================================================\n# APPLICATION\n# =============================================================================\nNODE_ENV=\"development\"\n```\n\n---\n\n## 🗄️ Database Setup\n\n### Option 1: Neon (Recommended)\n\n1. **Create a Neon Project**\n   - Go to [Neon Console](https://neon.tech)\n   - Click \"Create Project\"\n   - Name your project (e.g., \"learning-assistant\")\n   - Select the closest region to you\n   - Click \"Create Project\"\n\n2. **Get Connection Details**\n   - In the Neon dashboard, go to \"Connection Details\"\n   - Select \"Pooled connection\" for `DATABASE_URL`\n   - Select \"Direct connection\" for `DATABASE_URL_UNPOOLED`\n   - Copy the connection strings\n\n3. **Enable pgvector Extension**\n   - In Neon Console, go to \"Branches\"\n   - Select your branch\n   - Go to \"Extensions\"\n   - Enable the `vector` extension\n\n### Option 2: Local PostgreSQL\n\nIf you prefer running PostgreSQL locally:\n\n```bash\n# macOS (using Homebrew)\nbrew install postgresql@15\nbrew services start postgresql@15\n\n# Ubuntu/Debian\nsudo apt update\nsudo apt install postgresql postgresql-contrib\nsudo systemctl start postgresql\n\n# Create database\ncreatedb learning_assistant\n```\n\nUpdate your `.env.local`:\n```env\nDATABASE_URL=\"postgresql://postgres:password@localhost:5432/learning_assistant?sslmode=disable\"\nDATABASE_URL_UNPOOLED=\"postgresql://postgres:password@localhost:5432/learning_assistant?sslmode=disable\"\n```\n\n### Prisma Commands\n\n```bash\n# Generate Prisma Client (after schema changes)\npnpm prisma generate\n\n# Push schema to database (creates/updates tables)\npnpm prisma db push\n\n# Create a new migration\npnpm prisma migrate dev --name migration_name\n\n# View database in Prisma Studio (GUI)\npnpm prisma studio\n\n# Reset database (WARNING: deletes all data)\npnpm prisma migrate reset\n```\n\n---\n\n## ▶️ Running the Application\n\n### Development Mode\n\n```bash\npnpm dev\n```\n\nThe app will be available at [http://localhost:3000](http://localhost:3000)\n\n### Production Build\n\n```bash\n# Build the application\npnpm build\n\n# Start production server\npnpm start\n```\n\n### Code Quality\n\n```bash\n# Run ESLint\npnpm lint\n\n# Type check\npnpm tsc --noEmit\n```\n\n---\n\n## 📜 Available Scripts\n\n| Command | Description |\n|---------|-------------|\n| `pnpm dev` | Start development server |\n| `pnpm build` | Build for production |\n| `pnpm start` | Start production server |\n| `pnpm lint` | Run ESLint |\n| `pnpm prisma generate` | Generate Prisma Client |\n| `pnpm prisma db push` | Push schema to database |\n| `pnpm prisma migrate dev` | Create and apply migrations |\n| `pnpm prisma studio` | Open Prisma database GUI |\n\n---\n\n## 📂 Project Structure\n\n```\n├── prisma/\n│   └── schema.prisma          # Database schema\n├── src/\n│   ├── app/\n│   │   ├── (auth)/           # Authentication pages\n│   │   │   ├── login/\n│   │   │   └── register/\n│   │   ├── (dashboard)/      # Protected dashboard pages\n│   │   │   ├── dashboard/\n│   │   │   │   ├── analytics/\n│   │   │   │   ├── chat/\n│   │   │   │   ├── library/\n│   │   │   │   ├── materials/\n│   │   │   │   └── settings/\n│   │   ├── api/              # API routes\n│   │   │   ├── auth/\n│   │   │   └── chat/\n│   │   ├── actions/          # Server Actions\n│   │   └── layout.tsx\n│   ├── components/          # React components\n│   ├── lib/                  # Utility libraries\n│   │   ├── auth.ts           # Better Auth config\n│   │   ├── db.ts             # Prisma client\n│   │   ├── knowledge.service.ts  # RAG pipeline\n│   │   └── usage.service.ts # Usage tracking\n│   └── middleware.ts         # Auth middleware\n├── .env.example              # Environment variables template\n├── package.json\n├── pnpm-lock.yaml\n├── tsconfig.json\n├── tailwind.config.ts\n└── next.config.ts\n```\n\n---\n\n## 🔑 API Keys Setup\n\n### 1. OpenRouter API Key\n\nOpenRouter provides access to 100+ AI models through a unified API.\n\n**Steps:**\n1. Go to [OpenRouter.ai](https://openrouter.ai)\n2. Sign up / Log in\n3. Navigate to \"Settings\" → \"API Keys\"\n4. Click \"Create New Key\"\n5. Copy the key (it starts with `sk-or-v1-`)\n6. Add to `.env.local`:\n   ```\n   OPENROUTER_API_KEY=\"sk-or-v1-xxxxxxxxxxxxx\"\n   ```\n\n**Usage:**\n- **Chat Model**: Google Gemini 2.5 Flash (default)\n- **Embeddings**: NVIDIA Llama Nemotron Embed VL (free tier)\n\n**Pricing:**\n- The app uses free models by default\n- You can upgrade to paid models anytime\n- Set spending limits in OpenRouter dashboard\n\n### 2. Better Auth Secret\n\nGenerate a secure secret for authentication:\n\n```bash\n# Generate a random 32-character secret\nopenssl rand -base64 32\n```\n\nOr use: https://generate-secret.vercel.app/32\n\n---\n\n## 🚢 Deployment\n\n### Vercel (Recommended)\n\n1. **Push to GitHub**\n   ```bash\n   git init\n   git add .\n   git commit -m \"Initial commit\"\n   git branch -M main\n   git remote add origin https://github.com/username/repo.git\n   git push -u origin main\n   ```\n\n2. **Deploy to Vercel**\n   - Go to [Vercel Dashboard](https://vercel.com/dashboard)\n   - Click \"Add New...\" → \"Project\"\n   - Import your GitHub repository\n   - In \"Environment Variables\", add all variables from `.env.example`\n   - Click \"Deploy\"\n\n3. **Update Production URLs**\n   After deployment, update these variables:\n   ```env\n   BETTER_AUTH_URL=\"https://your-app.vercel.app\"\n   ```\n\n### Environment Variables in Production\n\n| Variable | Production Value |\n|----------|-----------------|\n| `NODE_ENV` | `production` |\n| `BETTER_AUTH_URL` | `https://your-domain.com` |\n| `DATABASE_URL` | Neon pooled connection string |\n| `DATABASE_URL_UNPOOLED` | Neon direct connection string |\n\n---\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n#### 1. \"DATABASE_URL is missing\"\n\n**Solution:** Ensure your `.env.local` file exists and contains `DATABASE_URL`.\n\n```bash\n# Verify the file exists\nls -la .env.local\n```\n\n#### 2. Prisma Client not generated\n\n**Solution:** Run `pnpm prisma generate`\n\n```bash\npnpm prisma generate\n```\n\n#### 3. WebSocket connection errors\n\n**Solution:** Ensure the `ws` package is installed and configured correctly. The app uses WebSockets for database connections via Neon.\n\n#### 4. Authentication errors\n\n**Solution:** \n1. Verify `BETTER_AUTH_SECRET` is at least 32 characters\n2. Ensure `BETTER_AUTH_URL` matches your current URL\n3. Clear browser cookies and try again\n\n#### 5. OpenRouter API errors\n\n**Solution:**\n1. Verify your API key is correct\n2. Check your API key has sufficient credits\n3. Ensure the key starts with `sk-or-v1-`\n\n#### 6. Build errors\n\n**Solution:** Clear `.next` cache and rebuild:\n\n```bash\nrm -rf .next\npnpm build\n```\n\n### Getting Help\n\nIf you encounter issues not listed here:\n\n1. Check the error logs in your terminal\n2. Review the [Next.js documentation](https://nextjs.org/docs)\n3. Check the [Prisma documentation](https://www.prisma.io/docs)\n4. Open an issue on GitHub\n\n---\n\n## 📞 Support\n\n- **Documentation**: See the `/docs` folder for detailed specifications\n- **Issues**: Report bugs at the GitHub repository\n- **Discussions**: Use GitHub Discussions for questions\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- [Next.js](https://nextjs.org) - The React Framework\n- [Prisma](https://prisma.io) - Next-generation ORM\n- [Better Auth](https://www.better-auth.com) - Authentication for modern web apps\n- [OpenRouter](https://openrouter.ai) - Unified AI API\n- [Vercel](https://vercel.com) - Deploy with zero configuration\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjstarfilms%2Fai-powered_personalized_learning_assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjstarfilms%2Fai-powered_personalized_learning_assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjstarfilms%2Fai-powered_personalized_learning_assistant/lists"}