Magezi AI

Description

This Python-based application enables users to access Large Language Models (LLMs) via SMS. It integrates with Africa's Talking to handle SMS reception and response delivery. The application supports two LLM approaches:

• OpenAI API: Uses OpenAI's gpt-4o for processing requests.
• Local Models: Runs deepseek-r1 models (1.5B, 7B) locally, with potential for larger models depending on compute power.

Upon receiving an SMS, the application stores the message in a MongoDB database, processes it using the selected LLM, and then returns an abbreviated response via SMS (due to SMS character limits). The backend is built using FastAPI, and ngrok is used to expose the application for handling Africa's Talking callbacks.

Features

• Seamless SMS-based AI access without internet connectivity.
• Choice of LLMs between OpenAI API (gpt-4o) or self-hosted deepseek-r1 models.
• MongoDB integration for storing prompts and responses.
• FastAPI-powered backend with a structured API.
• Ngrok tunneling for webhook access.

Set Up Instructions

Prerequisites

Ensure you have the following installed on your system:

• Python 3.12 (Python 3.8+ might be sufficient)
• MongoDB (local or cloud-based, e.g., MongoDB Atlas)
• Ngrok (for exposing local ports)
• Africa's Talking API credentials
• OpenAI API Key (if using OpenAI models)

Installation

1. Clone repository:

   git clone https://github.com/joelmwaka/MageziAI.git
   cd MageziAI

2. Create and activate virtual environment:

   python3 -m venv venv
   source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Set environment variables: Create a .env file in the project root and add the following variables:

   MONGO_DB_URI=<MongoDB URI>
   MONGO_DB_NAME=<MongoDB Database Name>
   OPENAI_API_KEY=<OpenAI API Key>
   OLLAMA_HOST=<Ollama Server URL>
   AT_USERNAME=<AT Username>
   AT_API_KEY=<AT API Key>
   ASSISTANT_SHORTCODE=<AT Shortcode>

   Note: In the sections "Africa's Talking", "OpenAI", and "MongoDB", you will find instructions on how to get the required credentials.
5. Run the FastAPI server:

   uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Ngrok

1. Install ngrok by following the instructions on the ngrok website.
2. Run ngrok to expose the FastAPI server (We are running our server on port 8000. Adapt your command accordingly):

   ngrok http 8000

3. Copy the forwarding URL (e.g., https://<random_dtring>.ngrok-free.app)

Africa's Talking

1. Create an account on Africa's Talking.
2. Open the sandbox application and get the API key by going to 'Settings' then selecting 'API Key'. Follow the instructions to get the API key. Add this to the .env file (AT_API_KEY).
3. Get the AT username (Should be 'sandbox' by default). Add this to the .env file (AT_USERNAME).
4. Create a short code for testing purposes. This can be done by selecting 'SMS' then 'Shortcodes' and following the instructions. Add the shortcode created to the .env file (ASSISTANT_SHORTCODE).
5. Set up the callback URL for the shortcode by going to 'SMS' then 'Callback URLs' and then 'Incoming Messages'. Add the ngrok URL followed by /sms (e.g., https://<random_string>.ngrok-free.app/sms). Then submit the URL. Note: The Ngrok URL will change every time it is restarted.

Ollama Server

1. Install the Ollama server by following the instructions on the Ollama Website.
2. Run the Ollama server by running the following command:

   ollama serve

3. Pull the models by running the following command:

   ollama pull deepseek-r1:1.5b
   ollama pull deepseek-r1:7b

4. Copy the Ollama server URL (e.g., http://127.0.0.1:11434). Add this to the .env file (OLLAMA_HOST).

Open AI

1. Create an account on OpenAI. And create an API Key by following the instructions on the website. Add the API Key to the .env file (OPENAI_API_KEY).

MongoDB

1. Create an account on MongoDB Atlas.
2. Or run MongoDB locally by following the instructions on the MongoDB Website.
3. If running MongoDB locally, start the MongoDB server by running the command:

   mongod --dbpath /path/to/your/data

4. Copy the MongoDB URI and add it to the .env file (MONGO_DB_URI).
5. Create a database on MongoDB and add the name to the .env file (MONGO_DB_NAME).

Great job! You are now ready to test the application.

Usage

To test the application, use the phone simulator provided by Africa's Talking. This tool is free to use and allows you to simulate sending and receiving SMS messages.

1. Go to the Africa's Talking sandbox application.
2. Select 'Launch Simulator'.
3. In the simulator that pops up, enter a random phone number for testing purposes.
4. Open the SMS app on the simulator and send a message to the shortcode you created.
5. You should receive a response from the Magezi AI application as shown in the images at the top of this README file.

Further Improvements

• Google Search Integration: Enable fetching real-time data for more recent knowledge.

• Retrieval-Augmented Generation (RAG): Enhance responses by integrating document retrieval for domain-specific use cases (e.g., agriculture, health, finance).

• Multi-language Support: Extend the application to support multiple languages for a broader user base.

• Caching Responses: Implement caching for frequent queries to reduce API calls and response time.

Contributing

Feel free to contribute by submitting pull requests or reporting issues.

License

This project is licensed under the MIT License.