An intelligent AI-powered assistant that helps users understand and navigate the Somali Provisional Constitution. Built with Next.js, Google Gemini, and Memvid AI.
- Natural language understanding in Somali
- Accurate answers based on the Somali Provisional Constitution
- Context-aware responses using RAG technology
- Multi-chat support - Create and manage multiple conversation threads
- Chat history - Persistent storage using localStorage
- Sidebar navigation - Easy access to all your conversations
- Real-time responses - Streaming AI responses with loading indicators
- Markdown support - Rich text formatting in responses
- Modern, glassmorphic design
- Smooth animations and transitions
- Responsive layout for all devices
- Dark mode ready
- Accessible and user-friendly interface
- Hybrid search combining vector embeddings and keyword matching
- Special optimization for article number queries (e.g., "Qodobka 3aad")
- Contextual relevance scoring
- Top-K retrieval for accurate results
- Node.js 18.x or higher
- npm or yarn
- Google Gemini API Key (Get one here)
-
Clone the repository
git clone https://github.com/omartood/Dastuur-agent-.git cd Dastuur-agent- -
Install dependencies
npm install
-
Set up environment variables
Create a
.envfile in the root directory:GEMINI_API_KEY=your_gemini_api_key_here
-
Prepare the knowledge base
Place your Somali Constitution PDF in the
pdf/directory:pdf/Dastuurka_KMG_Soomaaliya.pdf -
Generate embeddings
Run the ingestion script to process the PDF and create embeddings:
npm run ingest
This will:
- Extract text from the PDF
- Split content into chunks
- Generate embeddings using Google Gemini
- Store the vector database in
data/store.json
-
Start the development server
npm run dev
-
Open your browser
Navigate to http://localhost:3000
dastur-agents/
├── app/ # Next.js app directory
│ ├── api/ # API routes
│ │ └── ask/ # Chat endpoint
│ ├── components/ # React components
│ │ └── Sidebar.tsx # Chat history sidebar
│ ├── globals.css # Global styles
│ ├── layout.tsx # Root layout
│ └── page.tsx # Main chat interface
├── lib/ # Core libraries
│ ├── chatStorage.ts # Chat persistence utilities
│ ├── gemini.ts # Gemini API integration
│ └── memvid.ts # Vector search & RAG
├── scripts/ # Utility scripts
│ ├── ingest.ts # PDF ingestion & embedding
│ ├── test-search.ts # Search testing utility
│ └── ...
├── data/ # Generated data
│ └── store.json # Vector database
├── pdf/ # Source documents
│ └── Dastuurka_KMG_Soomaaliya.pdf
├── .env # Environment variables
├── package.json # Dependencies
├── tsconfig.json # TypeScript config
└── README.md # This file
- Next.js 16 - React framework with App Router
- React 19 - UI library
- TypeScript - Type safety
- Tailwind CSS 4 - Utility-first styling
- Lucide React - Beautiful icons
- React Markdown - Markdown rendering
- Google Gemini AI - Large language model
- Memvid AI - Intelligent vector search & RAG pipeline
- pdf-parse - PDF text extraction
- Custom RAG Implementation - Context-aware retrieval
- Vector Embeddings - Semantic search with cosine similarity
- LocalStorage - Client-side chat persistence
- JSON Store - Vector database storage
// scripts/ingest.ts
1. Load PDF → Extract text
2. Split into semantic chunks
3. Generate embeddings via Gemini
4. Store in vector database// app/api/ask/route.ts
1. User asks question
2. Generate query embedding
3. Search vector database (hybrid: vector + keyword)
4. Retrieve top-K relevant chunks
5. Send to Gemini with context
6. Return AI-generated answer// lib/memvid.ts
Score = (0.6 × Vector_Similarity) + (0.4 × Keyword_Match)
+ Special boost for article number queries| Command | Description |
|---|---|
npm run dev |
Start development server |
npm run build |
Build for production |
npm start |
Start production server |
npm run lint |
Run ESLint |
npm run ingest |
Process PDF and generate embeddings |
Edit lib/memvid.ts to customize:
// Number of results to retrieve
const topK = 5;
// Vector vs Keyword weighting
score = cosine * 0.6 + kwScore * 0.4;
// Chunk size for document splitting
const chunkSize = 1000;- Colors: Edit
tailwind.config.ts - Styles: Modify
app/globals.css - Components: Update files in
app/components/
Users can create multiple conversation threads, each with its own history. Chats are automatically saved and can be switched between seamlessly.
The system recognizes Somali article patterns (e.g., "Qodobka 3aad") and applies special scoring to ensure the correct article is retrieved, not just table of contents entries.
Using RAG, the AI retrieves relevant sections from the constitution before generating answers, ensuring accuracy and grounding in the actual document.
All conversations are saved in the browser's localStorage, allowing users to return to previous discussions anytime.
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the ISC License.
Omar Tood
- GitHub: @omartood
- Google Gemini AI for providing the language model
- The Somali government for making the constitution publicly available
- The open-source community for amazing tools and libraries
If you have any questions or need help, please:
- Open an issue on GitHub
- Contact the maintainer
- Multi-language support (English, Arabic)
- Voice input/output
- Export chat history
- Share conversations
- Advanced search filters
- Mobile app version
- Offline mode
- User authentication
- Cloud sync for chat history
Made with ❤️ for the Somali people
⭐ Star this repo if you find it helpful!