feat: make LearnPath provider-agnostic (any OpenAI-compatible LLM)

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,36 @@
+name: Bug report
+description: Report a problem with LearnPath
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including any console/server errors.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Set LLM_PROVIDER to ...
+        2. Open /quiz and ...
+        3. See error
+    validations:
+      required: true
+  - type: input
+    id: provider
+    attributes:
+      label: Provider and model
+      placeholder: openai / gpt-4o-mini
+    validations:
+      required: true
+  - type: input
+    id: node
+    attributes:
+      label: Node version
+      placeholder: "20.x"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question / discussion
+    url: https://github.com/aimanmalib/learnpath/discussions
+    about: Ask questions and discuss ideas before opening an issue.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,31 @@
+name: Feature request
+description: Suggest an idea or improvement for LearnPath
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What are you trying to do that LearnPath doesn't support today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - New LLM provider preset
+        - New study feature
+        - SM-2 algorithm improvement
+        - UI / accessibility
+        - Documentation
+        - Other
+    validations:
+      required: true

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: ["18.x", "20.x"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build
+        run: npm run build
+        env:
+          MIMO_API_KEY: dummy-key-for-build

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to LearnPath
+
+Thanks for your interest in improving LearnPath. This project is a
+provider-agnostic adaptive learning platform (Next.js + TypeScript) that runs
+on any OpenAI-compatible LLM endpoint. Contributions of all sizes are welcome
+— docs fixes, new provider presets, UI improvements, and bug reports all help.
+
+## Getting started
+
+```bash
+git clone https://github.com/aimanmalib/learnpath.git
+cd learnpath
+npm install
+
+echo 'LLM_PROVIDER=openai' > .env.local
+echo 'OPENAI_API_KEY=*** .env.local
+
+npm run dev      # http://localhost:3000
+npm test         # 116 tests should pass
+```
+
+## Development workflow
+
+1. Fork the repo and create a feature branch: `git checkout -b feat/my-change`
+2. Make your change with tests.
+3. Run the full local gate before pushing:
+   ```bash
+   npx tsc --noEmit     # type check
+   npm test             # vitest
+   npm run build        # production build
+   ```
+4. Commit using [Conventional Commits](https://www.conventionalcommits.org/)
+   (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `ci:`).
+5. Open a pull request against `main`. CI runs type check + tests + build on
+   Node 18/20 — keep it green.
+
+## Adding a new LLM provider
+
+LearnPath talks to any OpenAI-compatible `/chat/completions` endpoint, so most
+providers need only a preset entry. In `src/lib/mimo-client.ts`, add to
+`PROVIDER_PRESETS`:
+
+```ts
+myprovider: {
+  baseUrl: 'https://api.myprovider.com/v1',
+  authStyle: 'bearer',          // 'bearer' or 'api-key'
+  model: 'default-model-name',
+  envKey: 'MYPROVIDER_API_KEY',
+  envBase: 'MYPROVIDER_BASE_URL',
+},
+```
+
+Then add a test in `tests/lib/multi-backend.test.ts` mirroring the existing
+provider cases.
+
+## Good first issues
+
+- Add a provider preset (Together, Groq, DeepSeek, Mistral, ...)
+- Add a new study feature (essay grading, flashcard import/export)
+- Improve the SM-2 spaced repetition algorithm
+- Accessibility / responsive UI improvements
+
+## Code style
+
+- TypeScript with strict mode (see `tsconfig.json`)
+- Vitest for tests
+- Next.js App Router conventions
+- Keep components small and focused
+
+## Reporting bugs / requesting features
+
+Use the issue templates (bug report / feature request). Include repro steps,
+your provider/model, and your Node version for bugs.
+
+## License
+
+By contributing, you agree your contributions are licensed under the MIT
+License, the same as the project.

README.md

@@ -1,9 +1,17 @@
 # 🎓 LearnPath
 
-**Adaptive Learning Platform powered by Xiaomi MiMo V2.5 Pro**
+**Adaptive Learning Platform for any OpenAI-compatible LLM**
 
 > AI-driven personalized education — quizzes, flashcards, learning roadmaps, progress tracking, and concept mapping.
 
+[![Next.js 14](https://img.shields.io/badge/Next.js-14-black.svg)](https://nextjs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue.svg)](https://www.typescriptlang.org/)
+[![CI](https://github.com/aimanmalib/learnpath/actions/workflows/ci.yml/badge.svg)](https://github.com/aimanmalib/learnpath/actions/workflows/ci.yml)
+[![Tests: 116](https://img.shields.io/badge/tests-116-brightgreen.svg)](tests/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Works with **OpenAI, OpenRouter, Ollama, llama.cpp, Xiaomi MiMo**, or any endpoint that speaks the OpenAI `/chat/completions` protocol. Pick a provider with one env var — no code changes.
+
 ---
 
 ## Architecture
@@ -23,7 +31,7 @@
 │  └────────────────────┬───────────────────┘             │
 │                       │                                  │
 │  ┌────────────────────▼───────────────────┐             │
-│  │           Custom Hooks (useMiMo)        │             │
+│  │         Custom Hooks (useMiMo)        │             │
 │  │     SSE streaming │ token tracking      │             │
 │  └────────────────────┬───────────────────┘             │
 │                       │                                  │
@@ -34,8 +42,8 @@
 │  └────────────────────┬───────────────────┘             │
 │                       │                                  │
 │  ═══════════════════════════════════════════             │
-│  Xiaomi MiMo V2.5 Pro API                               │
-│  token-plan-sgp.xiaomimimo.com/v1                       │
+│  Any OpenAI-compatible /chat/completions endpoint        │
+│  (OpenAI · OpenRouter · Ollama · MiMo · ...)             │
 └─────────────────────────────────────────────────────────┘
 ```
 
@@ -48,37 +56,32 @@
 | **Learning Roadmap** | Personalized learning paths by topic/level | 0.5M |
 | **Progress Tracker** | Visual analytics dashboard | 0.3M |
 | **Concept Map** | Knowledge graph exploration | 0.5M |
-| **AI Chat** | Streaming MiMo conversation | 0.8M |
+| **AI Chat** | Streaming LLM conversation | 0.8M |
 
 **Daily Total: ~3.1M tokens**
 
-## Token Consumption Report
+## Supported Providers
 
-| Metric | Value |
-|--------|-------|
-| Daily token consumption | ~3.1M tokens |
-| Per-session (avg quiz) | ~8K tokens |
-| Primary model | mimo-v2.5-pro |
-| API endpoint | `token-plan-sgp.xiaomimimo.com/v1` |
-| Auth method | `api-key` header |
+LearnPath talks to any OpenAI-compatible `/chat/completions` endpoint. Built-in presets:
 
-## Why MiMo?
+| Provider | `LLM_PROVIDER` | Default model | Auth | Key env var |
+|----------|----------------|---------------|------|-------------|
+| OpenAI | `openai` | `gpt-4o-mini` | Bearer | `OPENAI_API_KEY` |
+| OpenRouter | `openrouter` | `openai/gpt-4o-mini` | Bearer | `OPENROUTER_API_KEY` |
+| Ollama (local) | `ollama` | `llama3.1` | Bearer | `OLLAMA_BASE_URL` |
+| Xiaomi MiMo | `mimo` | `mimo-v2.5-pro` | api-key | `MIMO_API_KEY` |
 
-1. **Structured output** — MiMo excels at generating consistently formatted JSON for quizzes, flashcards, and roadmaps
-2. **SSE streaming** — Real-time token-by-token responses via `reasoning_content` field for interactive learning
-3. **Cost efficiency** — High-volume token consumption across 6 features requires affordable per-token pricing
-4. **Reasoning depth** — Chain-of-thought reasoning enables detailed explanations in quiz answers
-5. **API compatibility** — OpenAI-compatible endpoint simplifies Next.js integration
+Set `LLM_PROVIDER` + the matching key (or just `LLM_API_KEY`). Override `LLM_BASE_URL` / `LLM_MODEL` for any other compatible endpoint. The right auth header (bearer vs api-key) is chosen automatically. Quiz answers and chat responses surface a model's `reasoning_content` when available, but it isn't required.
 
 ## Quick Start
 
 ```bash
 # Install dependencies
 npm install
 
-# Set environment variables
-export MIMO_API_KEY="your-key-here"
-
+# Set environment — pick any provider (OpenAI shown here)
+echo 'LLM_PROVIDER=openai' > .env.local
+echo 'OPENAI_API_KEY=*** development
 # Development
 npm run dev
 
@@ -98,12 +101,12 @@ npm test
 - SM-2 algorithm (spaced repetition)
 - Vitest (testing)
 
-## API Details
+## LLM Backend
 
-- **Endpoint**: `https://token-plan-sgp.xiaomimimo.com/v1/chat/completions`
-- **Model**: `mimo-v2.5-pro`
-- **Auth**: `api-key` header (NOT `Authorization: Bearer`)
-- **Streaming**: SSE with `reasoning_content` field
+- **Protocol**: OpenAI-compatible `/chat/completions`
+- **Providers**: OpenAI, OpenRouter, Ollama, llama.cpp, Xiaomi MiMo, or any compatible endpoint
+- **Auth**: bearer token or `api-key` header, selected automatically per provider
+- **Config**: set `LLM_PROVIDER` + the provider's API key env var
 
 ## License
 

package.json

@@ -2,7 +2,7 @@
   "name": "learnpath",
   "version": "1.0.0",
   "private": true,
-  "description": "Adaptive Learning Platform powered by Xiaomi MiMo V2.5 Pro",
+  "description": "Adaptive Learning Platform for any OpenAI-compatible LLM",
   "scripts": {
     "dev": "next dev",
     "build": "next build",

src/app/layout.tsx

@@ -3,7 +3,7 @@ import "./globals.css";
 
 export const metadata: Metadata = {
   title: "LearnPath — Adaptive Learning Platform",
-  description: "AI-powered adaptive learning with MiMo V2.5 Pro",
+  description: "AI-powered adaptive learning with any OpenAI-compatible LLM",
 };
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {

src/app/page.tsx

@@ -14,7 +14,7 @@ export default function Home() {
     <main className="min-h-screen p-8 max-w-4xl mx-auto">
       <div className="text-center mb-12">
         <h1 className="text-4xl font-bold mb-2">🎓 LearnPath</h1>
-        <p className="text-lg text-gray-600">Adaptive Learning Platform powered by Xiaomi MiMo V2.5 Pro</p>
+        <p className="text-lg text-gray-600">Adaptive Learning Platform for any OpenAI-compatible LLM</p>
         <p className="text-sm text-gray-400 mt-1">AI-driven quizzes, flashcards, and personalized roadmaps</p>
       </div>
 
@@ -31,7 +31,7 @@ export default function Home() {
       </div>
 
       <div className="mt-12 text-center text-sm text-gray-400">
-        <p>Powered by Xiaomi MiMo V2.5 Pro • API: token-plan-sgp.xiaomimimo.com/v1</p>
+        <p>Provider-agnostic • Runs on OpenAI, OpenRouter, Ollama, MiMo, or any compatible endpoint</p>
       </div>
     </main>
   );