MaSSTeck/aloc-ai-tutor-agent

Interactive Socratic AI Exam Tutor for West African syllabi (JAMB, WAEC, NECO). Grounded with verified curriculum data, progressive hints, and step-by-step reasoning via ALOC API. # ALOC AI Exam Tutor Agent 🤖 > An interactive terminal & programmatic AI tutoring engine for West African examination syllabi (JAMB, WAEC, NECO, Post-UTME), powered by **ALOC Station** and `@massteck/aloc-sdk`. --- ## What It Does 1. **Curriculum Grounding**: Dynamically fetches verified WAEC/JAMB questions by subject and topic. 2. **Adaptive Socratic Tutoring**: Evaluates student attempts, provides progressive hints without spoiling answers, and explains key scientific concepts. 3. **Misconception Diagnosis**: Leverages ALOC's L3 step-by-step reasoning layer to identify why a student chose a distractor option. --- ## Quickstart ### 1. Clone the Repository ```bash git clone github.com cd aloc-ai-tutor-agent npm install ``` ### 2. Configure Your Environment ```bash cp .env.example .env ``` Add your `ALOC_API_KEY`: ```env ALOC_API_KEY=alc_live_your_key_here ALOC_BASE_URL=dev.aloc.com.ng ``` > If you don't have an API key yet, register for a free ALOC account to get 1,000 credits/month, or run immediately in **Demo Mode**. ### 3. Run Interactive Tutor CLI ```bash npm run dev ``` --- ## Programmatic Code Example ```typescript import { QuestionsApi, Configuration } from "@massteck/aloc-sdk"; const apiKey = process.env.ALOC_API_KEY || ""; const aloc = new QuestionsApi( new Configuration({ apiKey: apiKey, basePath: process.env.ALOC_BASE_URL || "dev.aloc.com.ng", headers: { "X-API-Key": apiKey, }, }) ); // Fetch WAEC Chemistry questions on Organic Chemistry const response = await aloc.listQuestions({ examType: "waec", subject: "chemistry", topic: "Organic Chemistry", limit: 5, }); console.log(`Loaded ${response.data.length} verified curriculum questions.`); ``` --- ## License MIT © MaSSTeck / ALOC Station.