Neura is a Django-powered backend for creating smart assistants that respond to WhatsApp messages using a custom knowledge base. It uses semantic search to find the most relevant answers and falls back to Gemini for generative replies when necessary. Built as a side project, Neura focuses on simplicity, private use, and learning.
- Knowledge Base: Upload and manage knowledge entries per assistant.
- Semantic Search: Fast, relevant answers using vector embeddings.
- Gemini LLM Fallback: Uses Google Gemini for generative answers when knowledge base is insufficient.
- WhatsApp Integration: Webhook for Twilio WhatsApp, setup instructions, and group support.
- User Authentication: JWT-based registration, login, password reset, and email verification.
- Admin Dashboard: Powerful Django admin for assistants and knowledge entries.
- REST API: Fully documented endpoints for all operations.
- Media Support: Upload avatars for assistants.
- Testing: Comprehensive test suite for endpoints and logic.
neura/
├── assistants/ # Assistant models, views, admin, semantic search, Gemini integration
├── userauth/ # User registration, login, password reset, email verification
├── whatsapp/ # WhatsApp webhook and setup instructions
├── neura/ # Django project settings, URLs, WSGI/ASGI
├── requirements.txt # Python dependencies
└── README.md # This file
1. Clone the Repository
git clone https://github.com/OnatadeTobi/neura.git
cd neura2. Install Dependencies
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
pip install -r requirements.txt3. Environment Variables
Create a .env file in the project root with the following keys:
SECRET_KEY=your-django-secret
DEBUG=True
DB_NAME=your_db
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_HOST=localhost
DB_PORT=5432
EMAIL_HOST_USER=your_email_user
EMAIL_HOST_PASSWORD=your_email_password
DEFAULT_FROM_EMAIL=your_from_email
GEMINI_API_KEY=your_gemini_api_key
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
SOCIAL_AUTH_PASSWORD=your_social_auth_password
4. Database Setup
python manage.py migrate5. Create Superuser
python manage.py createsuperuser6. Run the Server
python manage.py runserverPostgreSQL is the default database for Neura.
-
Why PostgreSQL?
Neura uses Django'sArrayFieldfor efficient storage and querying of vector embeddings and other array data.ArrayFieldis only supported by PostgreSQL, making it the best choice for features like semantic search and storing embeddings natively. -
Alternative (SQLite or other DBs):
If you want to use Django's default SQLite database (or another DB that doesn't supportArrayField), you must change allArrayFieldusages in your models toJSONField.Note:
JSONFieldis supported by both PostgreSQL and SQLite (Django 3.1+), but you may lose some performance and advanced querying capabilities for arrays. -
How to switch:
- Replace the
ArrayFieldfields in the assistants models withJSONField. - Run migrations:
python manage.py makemigrations python manage.py migrate
- Update any code that relies on array-specific queries to use JSON-compatible logic.
- Replace the
-
PostgreSQL Setup:
Make sure you have a running PostgreSQL instance and your.envis configured as shown in the Quickstart section.
- Create assistants via the API or Django admin.
- Upload knowledge base entries for each assistant.
- Assign unique tag names for WhatsApp mentions.
- Send a message to your Twilio WhatsApp number.
- Mention the assistant using
@tag_name: your question. - The assistant replies using semantic search or Gemini fallback.
- Register and login to obtain JWT tokens.
- Use
Authorization: Bearer <token>for authenticated endpoints.
POST /api/auth/register/— Register userPOST /api/auth/login/— Login userPOST /api/auth/verify-email/— Verify email with OTPPOST /api/auth/password-reset/— Request password resetPOST /api/auth/set-new-password/— Set new password
GET/POST /api/assistants/— List/create assistantsGET/PUT/DELETE /api/assistants/<id>/— Assistant detail/update/delete
GET/POST /api/assistants/knowledge/?assistant=<id>— List/create entriesGET/PUT/DELETE /api/assistants/knowledge/<id>/— Entry detail/update/delete
GET /api/assistants/answer/?query=...&assistant_id=...— Get answer from assistant
GET /api/whatsapp/setup/<assistant_id>/— Get WhatsApp setup instructionsPOST /api/whatsapp/webhook/— Twilio webhook for WhatsApp messages
python manage.py test assistants.tests- Visit
/admin/and login with your superuser credentials. - Manage users, assistants, and knowledge base entries.
- View avatars, knowledge entry counts, and more.
1. Send a message to your Twilio WhatsApp number
2. Send a message: @your_tag_name: What do you know about me?
3. The assistant will reply based on your knowledge base or Gemini.
- Add new platforms by extending the
Assistantmodel and webhook logic. - Integrate more LLMs or embedding models as needed.
- Never commit your
.envfile or secrets. - Use HTTPS and secure your Twilio webhook endpoint in production.
- Set
DEBUG=Falsein production.
Pull requests and issues are welcome! Please open an issue to discuss your ideas.