Certifiedunder the RAG-Based AI Assistant module in the Agentic AI Essentials program.##Introduction
Traditional e-commerce platforms often struggle to provide personalized and immediate customer support. Many online stores still depend on human customer-service agents, static FAQ pages, or manually maintained product descriptions. While these approaches can provide useful information, they often create friction when customers need quick answers about product availability, specifications, pricing, warranties, payment methods, business hours, or available services.
This challenge becomes particularly important in electronics e-commerce, where customers frequently ask specific questions before making a purchase. A customer may want to know whether a particular Samsung or iPhone model is available, whether a screen protector can be installed, whether M-Pesa is accepted, or where the physical shop is located. If this information is difficult to find, the customer may leave the store without completing the purchase.
This project introduces Osman AI, an AI-powered shopping assistant integrated into the Khalid & Osman Accessories e-commerce platform. The system combines a modern React storefront with a Python/FastAPI backend and a Retrieval-Augmented Generation (RAG) pipeline. The objective is to provide customers with a more direct and intelligent way of interacting with the store while keeping the AI grounded in the business's own verified knowledge base.
The assistant is designed to function as a digital store representative. Instead of relying solely on the general knowledge stored inside a Large Language Model (LLM), Osman AI first searches the store's internal knowledge base for information relevant to the customer's question. The retrieved information is then provided to the language model as context before an answer is generated.
This architecture is important because a general-purpose LLM does not inherently know the specific products, policies, services, business hours, payment methods, or physical location of a particular store. Without retrieval, the model could potentially provide information that is inaccurate or unrelated to the business. RAG addresses this problem by connecting the language model to a controlled collection of store-specific documents.
The knowledge base consists of local .txt files containing information about the business, products, services, policies, and contact information. These documents represent the controlled source of information used by the retrieval system. For example, the knowledge base specifies that the shop is located on Luthuli Avenue, Nairobi, and that customers can make payments through M-Pesa using the official business number 0726228805. Customers who require directions can contact the business using the contact information provided in the knowledge base.
Before the information can be retrieved, the documents go through an ingestion process. The text is divided into smaller chunks, converted into numerical vector representations using the sentence-transformers/all-MiniLM-L6-v2 embedding model, and stored in a persistent ChromaDB vector database. When a customer submits a question, the same embedding approach is used to represent the query, allowing the system to search for semantically relevant information rather than relying only on exact keyword matching.
The project also incorporates lightweight query processing before retrieval. This includes whitespace normalization, lowercase conversion, empty-query protection, and correction of selected common misspellings. For example, a query such as "sumsung phone" can be normalized to "samsung phone", while "ipone" can be corrected to "apple iphone". These preprocessing steps improve retrieval without introducing an additional LLM solely for query rewriting.
RAG Project Scope and Capabilities
To ensure that the system has clearly defined boundaries, Osman AI operates within a controlled scope.
What Osman AI Does
Osman AI is designed to:
For location-related questions, the system can provide the verified shop location on Luthuli Avenue, Nairobi. If a customer needs additional directions or assistance locating the shop, they can be directed to contact the business using the contact information maintained in the knowledge base.
What Osman AI Does Not Do
The assistant is deliberately limited to prevent unsupported responses. It does not:
Therefore, the current system should be understood as a knowledge-grounded store assistant, rather than a general-purpose autonomous AI agent.
The overall architecture demonstrates how a React-based e-commerce interface, a FastAPI backend, Sentence Transformers embeddings, ChromaDB vector storage, LangChain orchestration, and the Groq LLM can work together to provide an intelligent and controlled customer-support experience.
The project also demonstrates an important principle of practical Agentic AI development: an AI system becomes more reliable when its capabilities are connected to appropriate tools, data sources, retrieval mechanisms, and clearly defined behavioral boundaries rather than depending entirely on the model's pretrained knowledge.
The Osman AI project was developed using a modular architecture that clearly separates the customer-facing e-commerce storefront from the artificial intelligence processing system. This separation was intentional because it allows each part of the application to perform its specific role without unnecessarily interfering with the other. The frontend is responsible for presenting products, managing the customer's shopping experience, handling the shopping cart, and providing the interface through which customers communicate with Osman AI. The backend, on the other hand, is responsible for processing AI requests, retrieving relevant business information, and generating responses based on the retrieved information.
Communication between these two layers is handled through a FastAPI REST API. When a customer submits a question through the Osman AI interface, the question is sent from the React frontend to the FastAPI backend. The backend then processes the query through the Retrieval-Augmented Generation (RAG) pipeline before returning the generated response to the frontend.
The methodology was therefore designed around four main principles: maintaining a clear separation of responsibilities, retrieving information from a controlled business knowledge base, using semantic search rather than relying only on exact keyword matching, and grounding AI-generated responses in retrieved business information. This approach allows Osman AI to provide business-specific assistance while preserving the structure and functionality of the original e-commerce application.
The customer-facing storefront was developed using React.js 19 and Vite. React was used because its component-based structure makes it possible to organize the storefront into reusable interface components while maintaining a responsive and interactive shopping experience. Vite was used as the development environment for the React application, providing a lightweight and efficient setup for running and developing the frontend.
The visual design of the storefront was implemented using Tailwind CSS 4. The interface follows a premium Navy Blue and Gold visual identity, with modern glassmorphism effects and Framer Motion animations used to improve the overall presentation and user experience. These design choices were intended to make the storefront feel modern and professional while maintaining a clear focus on product discovery and customer interaction.
The frontend manages the customer's shopping experience locally. React Context API is used to manage the state of the shopping cart, allowing product selections and quantities to remain available across the relevant components of the application.
An important consideration during the implementation was the handling of product prices. The cart primarily stores product identifiers and quantities rather than treating the price displayed in the browser as the authoritative source. This reduces the risk of relying on values that could potentially be manipulated on the client side. Product information can instead be resolved from the configured local catalogue when the customer proceeds toward checkout.
The checkout process was designed to remain simple and suitable for the existing business workflow. Before checkout, the application resolves the relevant product information from the configured local catalogue and constructs a URL-encoded WhatsApp message. The customer can therefore move from browsing products to contacting the business directly through WhatsApp without requiring a separate payment gateway or a complex transaction-processing backend.
The frontend also serves as the main interaction point for Osman AI. A customer can open the AI chat interface and submit a question about products, prices, warranties, store services, payment methods, location, business hours, or other information contained within the business knowledge base. Once a question is submitted, it is sent to the FastAPI backend for processing through the RAG pipeline.
The intelligence layer of the application was implemented as a Python-based REST API using FastAPI and LangChain. The backend acts as the central processing layer between the customer query, the business knowledge base, the vector database, and the language model.
When a customer submits a question, the backend first processes the query before performing semantic retrieval. Relevant information is then retrieved from the controlled knowledge base using Sentence Transformers and ChromaDB. The retrieved information is subsequently incorporated into a LangChain prompt and passed to the Groq language model for response generation.
The overall RAG workflow can be represented as follows:
React Frontend → FastAPI → Query Processing → Sentence Transformers → ChromaDB → Retrieved Context → LangChain Prompt → Groq LLM → Response → React Frontend
The key principle behind this architecture is that the language model is not expected to independently determine current facts about the business. Instead, the system first searches the controlled knowledge base and retrieves information that is relevant to the customer's question. That information is then provided to the language model as context for generating the final response.
This creates a clear distinction between information retrieval and language generation. ChromaDB and the embedding model are responsible for finding relevant business information, while the language model is responsible for interpreting that information and presenting it naturally to the customer.
This approach is particularly appropriate for an e-commerce assistant because business information such as prices, product availability, warranty policies, payment details, services, and operating information can change. Keeping such information within a controlled knowledge base provides a more manageable way of updating the information used by the assistant.
The foundation of the RAG system is a collection of local .txt documents stored in the project's data/ directory. These documents contain the business information that Osman AI is expected to use when responding to customer questions.
The knowledge base contains information relating to:
The knowledge base is treated as the controlled source of truth for business-specific responses. This means that information that is particularly important to the business is represented directly in the documents used by the retrieval system rather than being left entirely to the pretrained knowledge of the language model.
For example, the business information specifies that the shop is located on Luthuli Avenue, Nairobi. Customers who require additional directions or assistance locating the shop can be directed to contact the business using the contact information maintained within the knowledge base.
The payment information also specifies that M-Pesa is accepted and provides the current business M-Pesa number: 0726228805.
Including this information directly within the knowledge base allows it to become part of the retrieval process. When a customer asks about payment methods, the system can retrieve the relevant business information and use it as the basis for the generated response.
The same principle applies to other business information, including product details, warranties, services, business hours, and store policies. The knowledge base therefore provides the factual foundation upon which the AI assistant operates.
Before the knowledge-base information can be retrieved semantically, the documents must first be processed into smaller units. During backend initialization, the local knowledge-base documents are loaded and prepared for embedding and retrieval.
The project uses LangChain's RecursiveCharacterTextSplitter to divide the documents into smaller chunks. Rather than embedding an entire document as one large unit, the documents are divided into focused retrieval units so that individual business facts can be represented more effectively.
The current configuration is:
A chunk size of 500 characters provides a practical balance between retaining enough information to preserve meaning and keeping individual retrieval units sufficiently focused.
This is important because the knowledge base contains different types of information. A product entry may contain a product name, specifications, price, availability, and warranty information. Similarly, a policy document may contain several related statements. If the chunks are too large, unrelated information may be grouped together and make retrieval less precise. If they are too small, important information may lose the surrounding context required to understand it.
The selected 500-character configuration therefore provides relatively focused retrieval units while retaining enough surrounding information to represent individual business facts.
A 100-character overlap is applied between consecutive chunks.
The purpose of the overlap is to preserve continuity between neighbouring chunks. Information does not necessarily follow artificial character boundaries. For example, a product name, specification, price, or policy statement could begin near the end of one chunk and continue into the next.
Without overlap, dividing the document could separate related information into different retrieval units. This could make it more difficult for the embedding model to represent the complete meaning of the information.
With a 100-character overlap, the final portion of one chunk is repeated at the beginning of the following chunk. This provides additional context around the boundaries and reduces the likelihood that important information will be lost because of the way the document was divided.
This is particularly relevant in a RAG system because retrieval takes place at the chunk level. The system does not retrieve an entire knowledge-base document every time a customer asks a question. Instead, it retrieves the chunks that are considered most relevant to the query.
The combination of a 500-character chunk size and a 100-character overlap therefore provides a balance between focused retrieval and contextual continuity.
After the documents have been divided into chunks, each chunk is converted into a numerical vector representation using the Hugging Face Sentence Transformers model: sentence-transformers/all-MiniLM-L6-v2
The model was selected because it provides a practical balance between semantic-search capability and computational efficiency. This makes it suitable for the project's local retrieval requirements without introducing the need for a dedicated GPU.
The purpose of the embedding process is to represent the meaning of each knowledge-base chunk numerically. Customer queries are also converted into embeddings using the same model. The system can then compare the query representation with the representations of the stored knowledge-base chunks.
This allows retrieval to operate based on semantic similarity rather than depending exclusively on exact keyword matching. For example, a customer may ask: "Where is your shop located?" while the knowledge base may use different wording when describing the physical store location. Because both the query and the knowledge-base content are represented semantically, the retrieval system can identify the relationship between the two even when the exact wording is different.
The embedding model operates locally using the CPU, as confirmed during system initialization. This allows the semantic embedding process to be performed without requiring dedicated GPU hardware.
Once the knowledge-base chunks have been converted into embeddings, the resulting vectors are stored in ChromaDB.
The project uses ChromaDB with persistent local storage. This means that the generated vector representations remain available between application restarts instead of having to be recreated every time the backend is launched. The collection used for the RAG documents is: rag_documents
The ingestion process also uses deterministic identifiers based on the source document and chunk index. This provides a consistent way of identifying individual chunks within the vector store. ChromaDB's upsert() operation is used when storing the chunks. This allows existing records to be updated rather than unnecessarily creating duplicate records during repeated ingestion.
This approach helps maintain consistency between the knowledge-base documents and the vector database. When the knowledge base is updated and re-ingested, the corresponding vector records can be updated accordingly.
The following output was captured during backend initialization and confirms that the major components of the RAG system were successfully loaded:
(.venv) osama@osama-HP-ZBook-14u-G5:~/osman-accessories-ai$ python -m src.app INFO:main: RAG Assistant... INFO:main: Groq model: llama-3.1-8b-instant INFO:vectordb: ChromaDB... INFO:telemetry.product.posthog: telemetry enabled. INFO:vectordb: embedding model: sentence-transformers/all-MiniLM-L6-v2 INFO:SentenceTransformer: pytorch device_name: cpu
The initialization output provides evidence that the application successfully recognized the RAG assistant, configured the Groq language model as llama-3.1-8b-instant, initialized ChromaDB, loaded the sentence-transformers/all-MiniLM-L6-v2 embedding model, and selected the CPU as the PyTorch execution device.
Before semantic retrieval takes place, each customer query passes through a lightweight preprocessing stage. The purpose of this stage is to make customer input more consistent and improve the likelihood of retrieving the correct information.
The preprocessing pipeline includes whitespace normalization, lowercase normalization, empty-query protection, and selected deterministic typo correction.
In addition, the system implements deterministic correction for selected common spelling mistakes. Examples include:
"sumsung phone" → "samsung phone""ipone" → "apple iphone"These corrections are intentionally lightweight and deterministic. The system does not introduce another language model simply to rewrite every incoming query. Instead, known common errors are corrected before semantic retrieval. This provides a practical way of improving retrieval for common customer typing mistakes while keeping the query-processing pipeline simple and computationally efficient.
After preprocessing, the normalized customer query is converted into an embedding using the same Sentence Transformers model that was used during knowledge-base ingestion. The resulting query vector is compared with the vector representations stored in ChromaDB. The retrieval process then identifies the knowledge-base chunks that are most relevant to the meaning of the customer's question.
The current retrieval configuration uses:
The Top-K value determines the maximum number of candidate chunks initially considered for a query. In this implementation, the three most relevant chunks are retrieved before relevance filtering is applied.
The distance threshold provides an additional control over the relevance of the retrieved information. Chunks whose distance exceeds the configured threshold are excluded from the final context supplied to the language model.
The threshold was selected through controlled retrieval evaluation with the aim of maintaining a practical balance between retrieval coverage and relevance. A threshold that is too restrictive could prevent useful information from being retrieved, while a threshold that is too permissive could allow unrelated information into the generation context.
The final retrieval configuration achieved a 100.00% Hit Rate and an MRR of 1.0000 on the project's 13-query evaluation dataset.
Once relevant knowledge-base chunks have been retrieved, they are combined into a contextual prompt using LangChain's prompt-processing mechanism.
The retrieved information is provided to the language model together with instructions that define how the response should be generated. The assistant is instructed to base its business-specific response on the supplied context and avoid inventing information that is not supported by the retrieved knowledge.
The grounded prompt is sent to the Groq API using the configured llama-3.1-8b-instant model. At this stage, the language model's primary responsibility is to interpret the retrieved information and present it in a natural conversational format. The business-specific facts used to answer the customer are supplied through the retrieval process rather than being independently determined from the model's pretrained knowledge.
Once the response has been generated, it is returned through the FastAPI backend to the React frontend, where it is displayed to the customer through the Osman AI chat interface. This architecture therefore establishes a clear relationship between the customer's question, the controlled business information, and the final response.
To measure the effectiveness of the retrieval component independently from the language-generation stage, a dedicated evaluation script named evaluate_retrieval.py was implemented.
The evaluation dataset contains 13 predefined customer queries. Each query is associated with an expected source document from the knowledge base. The purpose of this evaluation is to determine whether the retrieval system can identify the appropriate business information before the language model generates a response.
The evaluation covers several categories of customer intent, including:
Two primary retrieval metrics were used.
Hit Rate measures whether the expected source document appears within the retrieved results. It can be expressed as:
Hit Rate = Number of queries where the expected source is retrieved / Total number of queries
A Hit Rate of 100% therefore means that the expected source was retrieved for every query in the evaluation set.
Mean Reciprocal Rank (MRR) evaluates not only whether the correct source was retrieved but also how highly it was ranked. A correct result appearing at Rank 1 receives a reciprocal rank of 1.0. A correct result at Rank 2 receives 0.5, while Rank 3 receives approximately 0.333.
MRR = (1/N) × Σ(1/rank_i) (where N represents the number of evaluation queries and rank_i represents the position of the first correct result).
The final evaluation produced:
All 13 expected source documents were successfully retrieved at Rank 1 during the final evaluation. These results demonstrate that the configured retrieval pipeline performed successfully on the predefined evaluation dataset. In particular, the combination of query preprocessing, semantic embeddings, Top-K retrieval, and distance filtering was able to identify the expected knowledge-base source for each of the 13 test queries.
However, the results should be interpreted within the scope of the evaluation dataset. A perfect score on 13 predefined queries does not mean that every possible customer question will necessarily produce a perfect retrieval result. The evaluation should therefore be understood as a validated benchmark for the current knowledge base and retrieval configuration rather than a universal guarantee of system performance.
The RAG architecture maintains a separation between the original knowledge-base documents and their corresponding vector representations. Because these are separate layers, changing a .txt knowledge-base document does not automatically change an embedding that has already been stored in ChromaDB.
During development, the knowledge base was refined to improve the clarity and accuracy of the information presented to customers. Following these changes, the existing ChromaDB vector storage was cleared and the updated documents were re-ingested.
The re-ingestion process ensured that the vector database contained embeddings generated from the latest versions of the knowledge-base documents. This process was particularly important when updating information such as the M-Pesa payment number, shop location, business hours, product information, and service descriptions.
Maintaining consistency between the source documents and their corresponding embeddings is essential in a RAG architecture. If the source document is updated but the vector representation is not refreshed, the retrieval system may continue returning outdated information. The refresh and re-ingestion process therefore helped ensure that the retrieval layer reflected the current version of the business knowledge base used by the application.
To make the project reproducible, the application can be installed and executed using the following environment and setup procedure.
The project repository can first be cloned and the Python virtual environment created:
git clone https://github.com/Abdullahi-Ai/osman-accessories-ai.git cd osman-accessories-ai python -m venv .venv source .venv/bin/activate pip install -r requirements.txt
The environment configuration file is then created:
cp .env.example .env
The actual Groq API key should then be added to the .env file. API credentials should not be hard-coded into the source code or committed to a public repository.
The React storefront dependencies are installed from the store directory:
cd store npm install cd ..
The backend virtual environment is activated and the backend startup script is executed:
source .venv/bin/activate ./start_backend.sh
The FastAPI backend is configured to run locally on http://localhost:8000.
The frontend is started from a second terminal:
cd store npm run dev
The Vite development server is configured to run locally on http://localhost:5173.
Once both services are running, the developer can open the frontend in a web browser, browse the available products, and interact with Osman AI through the chat interface.
The methodology combines a React-based e-commerce storefront with a FastAPI AI backend and a locally managed Retrieval-Augmented Generation pipeline.
The frontend is responsible for the customer shopping experience, product presentation, cart management, checkout preparation, and communication with the AI assistant. The backend handles customer-query preprocessing, semantic embedding, vector retrieval, prompt construction, and communication with the Groq language model.
The knowledge base provides the controlled business information used by the assistant. Sentence Transformers converts both stored documents and customer queries into semantic representations, while ChromaDB provides persistent local vector storage for those representations. LangChain coordinates the retrieval and prompt-generation stages, while FastAPI provides the communication layer between the storefront and the AI processing engine.
The resulting architecture provides a structured foundation for grounded AI-assisted e-commerce. At the same time, it leaves room for future development, including integration with live inventory systems, larger retrieval evaluation datasets, improved query understanding, conversational memory, and controlled agentic functionality.
The resulting application successfully delivers an interactive e-commerce experience in which the AI assistant is connected to a controlled business knowledge base. The integration of the RAG pipeline allows the assistant to answer business-specific questions using information retrieved from the configured knowledge base rather than relying entirely on the pretrained knowledge of the language model.
The system was specifically designed to reduce unsupported responses concerning business information such as product prices, availability, warranties, services, payment methods, and store policies. Because the retrieval process supplies the relevant business context before response generation, the assistant can provide responses that are directly connected to the information maintained by the business.
The following test demonstrates the retrieval of Samsung product information:
Ask a question (or type 'quit'): do you have samsung phone Batches: 100%|████████████████████████| 1/1 INFO:httpx: Request: POST https://api.groq.com/openai/v1/chat/completions "HTTP/1.1 200 OK" Assistant: Based on the Retrieved Context, yes, we have Samsung phones available. Specifically, we have the following Samsung models in stock: Galaxy A54 (Variant 16) Price: 45,000 KES Availability: In Stock Warranty: 12-month warranty Galaxy A24 Price: 26,500 KES Availability: In Stock Warranty: 12-month warranty
The response demonstrates that the retrieval stage was able to identify relevant product information and provide sufficient context for the language model to construct a customer-facing answer. The response included multiple product attributes rather than only confirming that Samsung products were available.
The result is useful in an e-commerce context because customers may require several pieces of information before deciding whether to continue with a purchase. Product name, price, availability, and warranty information can all contribute to that decision.
The test also demonstrates the role of the knowledge base as the source of business-specific information. Product details used in the response were supplied through the retrieval process rather than being dependent entirely on the language model's pretrained knowledge.
In addition to product and inventory-related questions, the completed system was evaluated using queries concerning general business information. These tests examined whether Osman AI could retrieve and present information such as the physical store location, business hours, payment methods, warranty policies, and available services.
The retrieval architecture allowed these questions to be handled using the same controlled knowledge-base mechanism used for product queries. Instead of relying solely on the pretrained knowledge of the language model, the system searched the locally maintained business documents and supplied relevant information to the generation stage.
For example, questions concerning the location of the store could be matched against knowledge-base content describing the business location on Luthuli Avenue, Nairobi. Similarly, questions concerning payment methods could be answered using the business information specifying that M-Pesa is accepted.
This demonstrates that the RAG implementation was not limited to product retrieval. The same retrieval mechanism could be used across different categories of business information, allowing the assistant to provide responses concerning operational and customer-service information from the same controlled source.
The system was also tested using questions that were not directly related to the store's products or business operations. This test was included because customers may naturally ask general questions while interacting with an AI assistant.
Ask a question (or type 'quit'): what is the capital city of kenya Batches: 100%|████████████████████████| 1/1 INFO:httpx: Request: POST https://api.groq.com/openai/v1/chat/completions "HTTP/1.1 200 OK" Assistant: The capital city of Kenya is Nairobi.
The system successfully generated a concise response to the general knowledge question. This demonstrates that the language-generation component remained capable of handling conversational inputs beyond the specific business information contained in the knowledge base.
However, this test is considered separately from the retrieval benchmark. The 100.00% Hit Rate and MRR of 1.0000 reported in this study measure retrieval performance against the predefined business-information evaluation dataset. They do not represent a measurement of general-purpose language-model knowledge.
A dedicated evaluation script named evaluate_retrieval.py was implemented to measure the effectiveness of the retrieval component independently from the final language-generation stage.
The evaluation dataset contains 13 predefined customer queries. Each query is associated with an expected knowledge-base source. The queries represent several business-information categories, including Samsung products, iPhone products, Tecno products, accessories, store location, business hours, mission information, M-Pesa payments, warranty policy, phone setup services, screen protector installation, and common spelling mistakes.
The final evaluation produced:
All 13 expected source documents were successfully retrieved at Rank 1 during the final evaluation. These results demonstrate that the configured retrieval pipeline successfully identified the expected source documents for all queries in the predefined evaluation dataset and ranked the expected source first in each case.
The retrieval results also demonstrate the role of semantic embeddings in matching customer questions with stored business information.
The system uses the sentence-transformers/all-MiniLM-L6-v2 model to convert knowledge-base chunks and customer queries into numerical vector representations. This enables the retrieval process to compare the semantic relationship between the query and stored information rather than depending exclusively on identical keywords.
The combination of lightweight query preprocessing and semantic embedding provides a practical mechanism for connecting customer language with the controlled information contained in the business knowledge base. The semantic retrieval approach also reduces dependence on manually defining exact keyword rules for every possible way a customer could phrase a question.
The retrieval pipeline uses a Top-K value of 3 together with a distance threshold of 1.30.
The Top-K configuration determines the maximum number of candidate chunks initially considered for each query. In this implementation, up to three relevant chunks are retrieved before the distance threshold is applied.
The distance threshold provides an additional relevance control by filtering retrieved results that exceed the configured distance value. This reduces the possibility of passing unrelated information into the context used by the language model.
The final evaluation achieved a 100.00% Hit Rate and an MRR of 1.0000. Within the 13-query benchmark, this indicates that the configured Top-K and distance filtering did not prevent the expected source from being retrieved and ranked first.
After relevant knowledge-base chunks were retrieved, the information was supplied to the language-generation stage through the LangChain prompt-processing mechanism.
The purpose of this stage was to provide the language model with relevant business context before generating a customer-facing response. The prompt establishes instructions for using the supplied context and avoiding unsupported business information.
By placing retrieved business information within the generation process, the architecture establishes a stronger connection between the final response and the controlled knowledge base.
The completed implementation successfully integrated the AI functionality into the existing e-commerce storefront while maintaining the separation between the presentation layer and the AI processing layer.
The React frontend remained responsible for product presentation, shopping-cart functionality, and the customer-facing interface. The FastAPI backend provided the communication layer for AI requests, while the RAG pipeline handled query preprocessing, semantic embedding, vector retrieval, context construction, and response generation.
This separation allowed the AI functionality to operate independently from the presentation layer. The frontend did not need to directly manage the embedding model, vector database, or communication with the Groq language model.
Several technical challenges were encountered during the implementation and integration of the system. Addressing these challenges was necessary to obtain reliable operation of the completed application.
Taken together, the functional and retrieval results demonstrate that the implemented Osman AI architecture achieved its primary technical objectives within the scope of the current project.
The system provided an integrated e-commerce interface through which customers could browse products and communicate with the AI assistant. The backend processed customer queries through preprocessing, semantic embedding, vector retrieval, context construction, and grounded language generation.
The 100.00% Hit Rate and 1.0000 MRR indicate that the retrieval component successfully identified the expected source for every query in the evaluation dataset and placed the expected source at Rank 1. This is a strong result for the current benchmark and indicates that the selected chunking, embedding, Top-K, and distance-threshold configuration was suitable for the current knowledge-base structure.
Although the current results demonstrate successful operation of the implemented system, several improvements could increase its performance and practical usefulness as the application grows:
The results of the Osman AI implementation demonstrate that a Retrieval-Augmented Generation architecture can be integrated into an existing e-commerce application while maintaining separation between the storefront and the AI processing system.
The quantitative retrieval evaluation produced the following results:
Overall, the completed system provides a functional foundation for AI-assisted e-commerce and demonstrates how RAG can be used to connect a language model with domain-specific business information. The architecture also provides a clear path for future development through expanded evaluation, automated knowledge synchronization, improved query understanding, conversational memory, and controlled tool integration.
##Result
The resulting application successfully delivers an interactive e-commerce experience in which the AI assistant is connected to a controlled business knowledge base. The integration of the RAG pipeline allows the assistant to answer business-specific questions using information retrieved from the configured knowledge base rather than relying entirely on the pretrained knowledge of the language model.
The system was specifically designed to reduce unsupported responses concerning business information such as product prices, availability, warranties, services, payment methods, and store policies. Because the retrieval process supplies the relevant business context before response generation, the assistant can provide responses that are directly connected to the information maintained by the business.
The following test demonstrates the retrieval of Samsung product information:
Ask a question (or type 'quit'): do you have samsung phone Batches: 100%|████████████████████████| 1/1 INFO:httpx: Request: POST https://api.groq.com/openai/v1/chat/completions "HTTP/1.1 200 OK" Assistant: Based on the Retrieved Context, yes, we have Samsung phones available. Specifically, we have the following Samsung models in stock: Galaxy A54 (Variant 16) Price: 45,000 KES Availability: In Stock Warranty: 12-month warranty Galaxy A24 Price: 26,500 KES Availability: In Stock Warranty: 12-month warranty
The response demonstrates that the retrieval stage was able to identify relevant product information and provide sufficient context for the language model to construct a customer-facing answer. The response included multiple product attributes rather than only confirming that Samsung products were available.
The result is useful in an e-commerce context because customers may require several pieces of information before deciding whether to continue with a purchase. Product name, price, availability, and warranty information can all contribute to that decision.
The test also demonstrates the role of the knowledge base as the source of business-specific information. Product details used in the response were supplied through the retrieval process rather than being dependent entirely on the language model's pretrained knowledge.
In addition to product and inventory-related questions, the completed system was evaluated using queries concerning general business information. These tests examined whether Osman AI could retrieve and present information such as the physical store location, business hours, payment methods, warranty policies, and available services.
The retrieval architecture allowed these questions to be handled using the same controlled knowledge-base mechanism used for product queries. Instead of relying solely on the pretrained knowledge of the language model, the system searched the locally maintained business documents and supplied relevant information to the generation stage.
For example, questions concerning the location of the store could be matched against knowledge-base content describing the business location on Luthuli Avenue, Nairobi. Similarly, questions concerning payment methods could be answered using the business information specifying that M-Pesa is accepted.
This demonstrates that the RAG implementation was not limited to product retrieval. The same retrieval mechanism could be used across different categories of business information, allowing the assistant to provide responses concerning operational and customer-service information from the same controlled source.
The system was also tested using questions that were not directly related to the store's products or business operations. This test was included because customers may naturally ask general questions while interacting with an AI assistant.
Ask a question (or type 'quit'): what is the capital city of kenya Batches: 100%|████████████████████████| 1/1 INFO:httpx: Request: POST https://api.groq.com/openai/v1/chat/completions "HTTP/1.1 200 OK" Assistant: The capital city of Kenya is Nairobi.
The system successfully generated a concise response to the general knowledge question. This demonstrates that the language-generation component remained capable of handling conversational inputs beyond the specific business information contained in the knowledge base.
However, this test is considered separately from the retrieval benchmark. The 100.00% Hit Rate and MRR of 1.0000 reported in this study measure retrieval performance against the predefined business-information evaluation dataset. They do not represent a measurement of general-purpose language-model knowledge.
A dedicated evaluation script named evaluate_retrieval.py was implemented to measure the effectiveness of the retrieval component independently from the final language-generation stage.
The evaluation dataset contains 13 predefined customer queries. Each query is associated with an expected knowledge-base source. The queries represent several business-information categories, including Samsung products, iPhone products, Tecno products, accessories, store location, business hours, mission information, M-Pesa payments, warranty policy, phone setup services, screen protector installation, and common spelling mistakes.
The final evaluation produced:
All 13 expected source documents were successfully retrieved at Rank 1 during the final evaluation. These results demonstrate that the configured retrieval pipeline successfully identified the expected source documents for all queries in the predefined evaluation dataset and ranked the expected source first in each case.
The retrieval results also demonstrate the role of semantic embeddings in matching customer questions with stored business information.
The system uses the sentence-transformers/all-MiniLM-L6-v2 model to convert knowledge-base chunks and customer queries into numerical vector representations. This enables the retrieval process to compare the semantic relationship between the query and stored information rather than depending exclusively on identical keywords.
The combination of lightweight query preprocessing and semantic embedding provides a practical mechanism for connecting customer language with the controlled information contained in the business knowledge base. The semantic retrieval approach also reduces dependence on manually defining exact keyword rules for every possible way a customer could phrase a question.
The retrieval pipeline uses a Top-K value of 3 together with a distance threshold of 1.30.
The Top-K configuration determines the maximum number of candidate chunks initially considered for each query. In this implementation, up to three relevant chunks are retrieved before the distance threshold is applied.
The distance threshold provides an additional relevance control by filtering retrieved results that exceed the configured distance value. This reduces the possibility of passing unrelated information into the context used by the language model.
The final evaluation achieved a 100.00% Hit Rate and an MRR of 1.0000. Within the 13-query benchmark, this indicates that the configured Top-K and distance filtering did not prevent the expected source from being retrieved and ranked first.
After relevant knowledge-base chunks were retrieved, the information was supplied to the language-generation stage through the LangChain prompt-processing mechanism.
The purpose of this stage was to provide the language model with relevant business context before generating a customer-facing response. The prompt establishes instructions for using the supplied context and avoiding unsupported business information.
By placing retrieved business information within the generation process, the architecture establishes a stronger connection between the final response and the controlled knowledge base.
The completed implementation successfully integrated the AI functionality into the existing e-commerce storefront while maintaining the separation between the presentation layer and the AI processing layer.
The React frontend remained responsible for product presentation, shopping-cart functionality, and the customer-facing interface. The FastAPI backend provided the communication layer for AI requests, while the RAG pipeline handled query preprocessing, semantic embedding, vector retrieval, context construction, and response generation.
This separation allowed the AI functionality to operate independently from the presentation layer. The frontend did not need to directly manage the embedding model, vector database, or communication with the Groq language model.
Several technical challenges were encountered during the implementation and integration of the system. Addressing these challenges was necessary to obtain reliable operation of the completed application.
Taken together, the functional and retrieval results demonstrate that the implemented Osman AI architecture achieved its primary technical objectives within the scope of the current project.
The system provided an integrated e-commerce interface through which customers could browse products and communicate with the AI assistant. The backend processed customer queries through preprocessing, semantic embedding, vector retrieval, context construction, and grounded language generation.
The 100.00% Hit Rate and 1.0000 MRR indicate that the retrieval component successfully identified the expected source for every query in the evaluation dataset and placed the expected source at Rank 1. This is a strong result for the current benchmark and indicates that the selected chunking, embedding, Top-K, and distance-threshold configuration was suitable for the current knowledge-base structure.
Although the current results demonstrate successful operation of the implemented system, several improvements could increase its performance and practical usefulness as the application grows:
The results of the Osman AI implementation demonstrate that a Retrieval-Augmented Generation architecture can be integrated into an existing e-commerce application while maintaining separation between the storefront and the AI processing system.
The quantitative retrieval evaluation produced the following results:
Overall, the completed system provides a functional foundation for AI-assisted e-commerce and demonstrates how RAG can be used to connect a language model with domain-specific business information. The architecture also provides a clear path for future development through expanded evaluation, automated knowledge synchronization, improved query understanding, conversational memory, and controlled tool integration.