Akili - AI-Powered Nigerian Secondary Education Platform

Akili is a comprehensive AI-powered educational platform designed to help Nigerian secondary school students master their studies from Junior Secondary 1 (JS1) to Senior Secondary 3 (SS3). The platform leverages advanced AI models to generate personalized learning content, interactive assessments, and progress tracking aligned with the Nigerian curriculum.

Features

Core Learning Features

Class-Based Learning: Organized curriculum covering JS1, JS2, JS3, SS1, SS2, and SS3 class levels
Term Structure: Content organized by First, Second, and Third Term following the Nigerian academic calendar
AI-Powered Course Generation: Automatically creates comprehensive, personalized courses tailored to student's class level and subject
Interactive Lessons: Rich lesson content with mathematical formulas rendered using KaTeX
Practice Quizzes: FREE unlimited quizzes with instant feedback and detailed explanations
Mock Tests: Full-length practice tests (20 questions) to assess understanding

Assessment System

Continuous Assessment: Weekly and monthly tests with automatic grading
Grade Computation: Automatic grade calculation (A-F) based on Nigerian grading standards
Progress Reports: Term-end progress reports with position ranking and remarks

Teacher Features

Teacher Dashboard: Comprehensive view of assigned classes and students
Student Management: Enroll and manage students in classes
Assignment Creation: Create and distribute assignments with due dates
Class Analytics: View performance statistics and identify struggling students

Parent Portal

Child Progress Tracking: Monitor children's grades and academic progress
Payment Management: View payment history and credit balances
Notifications: Receive alerts for grades, assessments, and reports

Content Management

Curriculum Version Control: Track changes to curriculum content
Content Moderation Queue: Review AI-generated content before publication
Curriculum Update Requests: Request and approve curriculum modifications

User Experience

Progress Tracking: Track quiz scores, completion rates, and learning journey
Credit System: 10 free credits daily with referral bonuses
Dark Mode: Eye-friendly interface with automatic dark mode support
PWA Support: Install as a Progressive Web App on mobile devices
Referral System: Earn +2 daily credit limit for each successful referral

Technology Stack

Component	Technology	Version
Backend Framework	Django	5.2.8
Database	PostgreSQL	Latest
Frontend CSS	Tailwind CSS	3.x
AI Integration	Google Gemini + Groq	Multi-tier
Math Rendering	KaTeX	0.16.9
Payment Gateway	Paystack	REST API
Static Files	Whitenoise	6.6.0
WSGI Server	Gunicorn	21.2.0
Deployment	Render	Cloud

Getting Started

Prerequisites

Python 3.11+
PostgreSQL 14+
Node.js 18+ (for Tailwind CSS)
Git

Installation

Clone the repository

git clone <repository-url>
cd akili-platform

Create and activate virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install Python dependencies
```
pip install -r requirements.txt
```
Set up environment variables

Copy .env.example to .env and configure:
```
cp .env.example .env
```
Set up the database
```
python manage.py migrate
```
Seed curriculum data
```
python manage.py seed_curriculum
```
Create a superuser
```
python manage.py createsuperuser
```
Run the development server
```
python manage.py runserver 0.0.0.0:5000
```
Access the application
- Main site: http://localhost:5000
- Admin panel: http://localhost:5000/admin

Environment Variables

Development

SECRET_KEY=your-secret-key-here
DEBUG=True
DATABASE_URL=postgresql://user:pass@localhost/akili_dev
GEMINI_API_KEY=your-gemini-api-key
GROQ_API_KEY=your-groq-api-key

Production

SECRET_KEY=your-production-secret-key
DEBUG=False
DATABASE_URL=postgresql://user:pass@host/akili_prod
ALLOWED_HOSTS=your.domain.com
CSRF_TRUSTED_ORIGINS=https://your.domain.com
GEMINI_API_KEY=your-gemini-api-key
GROQ_API_KEY=your-groq-api-key
PAYSTACK_SECRET_KEY=your-paystack-secret-key
PAYSTACK_PUBLIC_KEY=your-paystack-public-key

Project Structure

akili-platform/
├── akili_project/           # Django project settings
│   ├── settings.py          # Configuration
│   ├── urls.py               # URL routing
│   └── wsgi.py               # WSGI entry point
├── core/                     # Core utilities
│   ├── utils/                # AI fallback, module generator
│   ├── middleware.py         # Rate limiting, error handling
│   └── services/             # Business logic services
├── curriculum/               # Curriculum management
│   ├── models.py             # SchoolLevel, Subject, Term, Topic
│   ├── fixtures/             # Seed data (31 subjects)
│   └── management/commands/  # Data migration scripts
├── courses/                  # Course management
│   ├── models.py             # Course, Module, CachedLesson
│   ├── views.py              # Course creation, viewing
│   └── forms.py              # Course creation forms
├── assessments/              # Assessment system (NEW)
│   ├── models.py             # Assessment, Grade, TeacherProfile, etc.
│   ├── views.py              # Dashboard views
│   └── templates/            # Assessment templates
├── quizzes/                  # Practice quizzes
├── users/                    # Authentication
│   └── models.py             # CustomUser model
├── payments/                 # Paystack integration
├── profiles/                 # User profile management
├── static/                   # CSS, JS, images
├── templates/                # HTML templates
├── requirements.txt          # Python dependencies
├── render.yaml               # Render deployment config
└── manage.py                 # Django CLI

Database Models

Curriculum App

Model	Description
`AcademicSession`	Academic year (e.g., 2024/2025)
`SchoolLevel`	JS1-SS3 class levels
`Subject`	31 subjects with level associations
`Term`	First, Second, Third Term
`Week`	14 weeks per term
`SubjectCurriculum`	Curriculum per subject/level/term
`Topic`	Individual topics per week
`StudentProgramme`	Student enrollment
`SubjectEnrolment`	Subject-specific tracking
`LegacyExamMapping`	JAMB/SSCE/JSS compatibility

Assessments App

Model	Description
`Assessment`	Weekly/monthly tests and exams
`AssessmentQuestion`	MCQ, short answer, essay questions
`AssessmentSubmission`	Student submissions with scores
`Grade`	Term grades (A-F with GPA)
`ProgressReport`	Term-end reports
`TeacherProfile`	Teacher accounts
`TeacherClass`	Class assignments
`Assignment`	Teacher-created assignments
`ParentProfile`	Parent accounts with children
`Notification`	System notifications
`ContentVersion`	Curriculum version control
`ContentModerationQueue`	AI content review
`CurriculumUpdateRequest`	Curriculum change requests

Credit System

Daily Allocation

10 free credits for all users (resets at midnight WAT)
+2 daily limit per successful referral (max 30)

Credit Costs

Action	Credits
Course Creation	5
Mock Test (20 questions)	5
AI Tutor Question	1
Practice Quiz	FREE

Purchase Packages

Package	Price	Credits
Starter	₦500	50
Standard	₦1,000	120
Premium	₦2,000	300

AI Integration

4-Tier Fallback System

Tier 1: Gemini 2.5 Flash (Primary - Fast, Free)
    ↓ (on failure)
Tier 2: Gemini Pro (High Quality, Paid)
    ↓ (on failure)
Tier 3: Groq API (Fast, Free)
    ↓ (on failure)
Tier 4: Circuit Breaker (Graceful Error + Credit Refund)

Token Limits (Memory Optimized)

Tier	Max Tokens
Gemini Flash	2,500
Gemini Pro	3,000
Groq	2,000

Assessment System

Assessment Types

WEEKLY: Weekly topic tests
MONTHLY: Monthly comprehensive tests
MIDTERM: Mid-term examinations
TERMINAL: End-of-term examinations

Grading Scale

Score	Grade	GPA	Remarks
70-100	A	4.0	Excellent
60-69	B	3.0	Very Good
50-59	C	2.0	Good
45-49	D	1.0	Fair
40-44	E	0.5	Pass
0-39	F	0.0	Fail

Management Commands

# Seed curriculum data (required after fresh install)
python manage.py seed_curriculum

# Migrate legacy courses (for upgrades from old version)
python manage.py migrate_legacy_courses

# Collect static files (production)
python manage.py collectstatic --noinput

Testing

# Run all tests
python manage.py test

# Run specific app tests
python manage.py test assessments -v 2
python manage.py test curriculum -v 2
python manage.py test courses -v 2

# Run with coverage
coverage run manage.py test
coverage report

Current Test Coverage: 138+ tests across all apps

Deployment

Render Deployment

The project includes render.yaml for one-click Render deployment:

Push code to GitHub
Connect repository to Render
Add environment variables in Render dashboard
Render automatically runs build.sh
Gunicorn starts with optimized settings

Production Configuration

gunicorn --bind=0.0.0.0:5000 \
         --workers=2 \
         --threads=2 \
         --worker-class=gthread \
         --max-requests=1000 \
         --max-requests-jitter=50 \
         --timeout=120 \
         akili_project.wsgi:application

API Endpoints

Course API

Endpoint	Method	Description
`/courses/api/subjects/`	GET	Get subjects by class level
`/courses/create/`	POST	Create new course
`/courses/<id>/`	GET	View course details

Assessment API

Endpoint	Method	Description
`/assessments/`	GET	List available assessments
`/assessments/<id>/`	GET/POST	Take assessment
`/assessments/grades/`	GET	View student grades

Security

Implemented Measures

CSRF protection on all forms
Password hashing via Django bcrypt
HTTPS enforcement in production
Secure cookie settings (HttpOnly, SameSite, Secure)
HTML sanitization with bleach for AI content
SQL injection protection via Django ORM
Request rate limiting with database cache
@login_required on all protected views

Security Headers (Production)

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Follow PEP 8 for Python code
Use Django coding style guidelines
Write tests for new features
Update documentation as needed

License

Support

For technical support or questions:

Create an issue in the repository
Contact the development team

Contributors

Ogechi Obinwa - (@Ogetec-python)
Stephen Ayankoso - (@Steve-ayan)

Built with love for Nigerian students

Name		Name	Last commit message	Last commit date
Latest commit History 185 Commits
akili_project		akili_project
assessments		assessments
core		core
courses		courses
curriculum		curriculum
payments		payments
quizzes		quizzes
static		static
templates		templates
users		users
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
build.sh		build.sh
manage.py		manage.py
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
render.yaml		render.yaml
requirements.txt		requirements.txt
runtime.txt		runtime.txt
tailwind.config.js		tailwind.config.js

Nwokike/Akili

Folders and files

Latest commit

History

Repository files navigation

Akili - AI-Powered Nigerian Secondary Education Platform

Table of Contents

Features

Core Learning Features

Assessment System

Teacher Features

Parent Portal

Content Management

User Experience

Technology Stack

Getting Started

Prerequisites

Installation

Environment Variables

Development

Production

Project Structure

Database Models

Curriculum App

Assessments App

Credit System

Daily Allocation

Credit Costs

Purchase Packages

AI Integration

4-Tier Fallback System

Token Limits (Memory Optimized)

Assessment System

Assessment Types

Grading Scale

Management Commands

Testing

Deployment

Render Deployment

Production Configuration

API Endpoints

Course API

Assessment API

Security

Implemented Measures

Security Headers (Production)

Contributing

Code Style

License

Support

Contributors

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages