Deploy Mbaza Legal AI Model with inference endpoint

README.md

@@ -1,3 +1,297 @@
 ---
-license: unknown
+title: Mbaza Legal AI Model
+language:
+- rw
+- en
+- fr
+tags:
+- legal
+- kinyarwanda
+- nlp
+- sentence-transformers
+- question-answering
+license: mit
 ---
+
+# 🇷🇼 Mbaza Legal AI Model
+
+**Multilingual Legal Assistant for Rwandan Laws** - Supporting Kinyarwanda, English, and French.
+
+## Model Description
+
+This model provides intelligent legal assistance for Rwandan laws, punishments, and legal procedures. It uses semantic search with sentence embeddings to match user queries with relevant legal articles and punishment information.
+
+### Key Features
+
+- **Multilingual Support**: Kinyarwanda, English, and French
+- **Greeting Detection**: Natural conversation in multiple languages
+- **Legal Article Retrieval**: Semantic search across Rwandan legal code
+- **Punishment Information**: Detailed penalty and sentencing information
+- **Context Tracking**: Maintains conversation history
+
+### Technical Details
+
+- **Base Model**: `sentence-transformers/all-MiniLM-L6-v2`
+- **Embedding Dimension**: 384
+- **Similarity Metric**: Cosine similarity
+- **Framework**: PyTorch + SentenceTransformers
+
+## Usage
+
+### Via Hugging Face Inference API
+
+```python
+import requests
+
+API_URL = "https://api-inference.huggingface.co/models/mugwaneza/mbaza-model"
+headers = {"Authorization": f"Bearer {YOUR_HF_TOKEN}"}
+
+def query(prompt):
+    response = requests.post(API_URL, headers=headers, json={"inputs": [prompt]})
+    return response.json()
+
+# Example usage
+result = query("Ibihano by'ubujura ni ibihe?")
+print(result["text"])
+```
+
+### Via Python Client
+
+```python
+from huggingface_hub import InferenceClient
+
+client = InferenceClient(token=YOUR_HF_TOKEN)
+
+response = client.post(
+    "mugwaneza/mbaza-model",
+    json={"inputs": ["Kwinjira aho umuntu atuye bitemewe namategeko"]}
+)
+print(response)
+```
+
+### Via cURL
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_HF_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"inputs":["Mwaramutse neza"]}' \
+  https://api-inference.huggingface.co/models/mugwaneza/mbaza-model
+```
+
+### For Mobile Apps (React Native, Flutter, Swift)
+
+```javascript
+// React Native / JavaScript
+const API_URL = "https://api-inference.huggingface.co/models/mugwaneza/mbaza-model";
+const HF_TOKEN = "your_token_here";
+
+async function queryLegalAI(prompt) {
+  const response = await fetch(API_URL, {
+    method: "POST",
+    headers: {
+      "Authorization": `Bearer ${HF_TOKEN}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ inputs: [prompt] })
+  });
+  
+  return await response.json();
+}
+
+// Usage
+const result = await queryLegalAI("What is the punishment for theft?");
+console.log(result.text);
+```
+
+### For Laravel Backend
+
+```php
+<?php
+
+namespace App\Services;
+
+use Illuminate\Support\Facades\Http;
+
+class MbazaLegalAI
+{
+    protected $apiUrl = 'https://api-inference.huggingface.co/models/mugwaneza/mbaza-model';
+    protected $token;
+    
+    public function __construct()
+    {
+        $this->token = config('services.huggingface.token');
+    }
+    
+    public function query($prompt, $userId = 'web_user')
+    {
+        $response = Http::withHeaders([
+            'Authorization' => "Bearer {$this->token}",
+            'Content-Type' => 'application/json'
+        ])->post($this->apiUrl, [
+            'inputs' => [$prompt, $userId]
+        ]);
+        
+        return $response->json();
+    }
+}
+
+// Usage in Controller
+$ai = new MbazaLegalAI();
+$result = $ai->query("Ibihano by'ubujura ni ibihe?");
+return response()->json($result);
+```
+
+## Example Queries
+
+### Greetings (Multilingual)
+
+```python
+# Kinyarwanda
+query("Mwaramutse neza")
+# Response: Mwaramutse neza, amakuru yawe?
+
+# English
+query("Good morning")
+# Response: Good morning, how can I help you with legal matters?
+
+# French
+query("Bonjour")
+# Response: Bonjour, comment puis-je vous aider?
+```
+
+### Legal Questions
+
+```python
+# Kinyarwanda
+query("Ibihano by'ubujura ni ibihe?")
+# Returns: Punishment information for theft
+
+# English
+query("What are the laws about corruption in Rwanda?")
+# Returns: Relevant legal articles on corruption
+
+# Mixed
+query("Kwinjira aho umuntu atuye bitemewe namategeko")
+# Returns: Laws about trespassing and unauthorized entry
+```
+
+### Punishment Queries
+
+```python
+query("Igihano cy'umuntu wakubise undi")
+# Returns: Punishment for assault
+
+query("What is the penalty for fraud?")
+# Returns: Detailed penalty information
+```
+
+## Response Format
+
+```json
+{
+  "text": "Main response text (formatted for display)",
+  "intent": "greeting|law|punishment|fallback",
+  "laws": [
+    {
+      "article": "Article 166",
+      "description": "...",
+      "punishment": "...",
+      "similarity": 0.85
+    }
+  ],
+  "punishments": [
+    {
+      "crime": "Theft",
+      "category": "Property crimes",
+      "penalty": "..."
+    }
+  ]
+}
+```
+
+## Datasets
+
+The model uses the following datasets:
+
+1. **Legal Code Dataset** (`dataset-all.csv`)
+   - Rwandan laws and articles
+   - Descriptions in Kinyarwanda, English, and French
+   - Article numbers, chapters, and categories
+
+2. **Penal Code** (`penal_code.csv`)
+   - Crime categories
+   - Punishment details
+   - Sentencing guidelines
+
+3. **Greetings** (`greetings.csv`)
+   - Multilingual greetings and responses
+   - Conversational patterns
+
+## Model Files
+
+- `inference.py` - Main inference endpoint
+- `assistant.py` - Core assistant logic
+- `retriever.py` - Semantic search and embedding management
+- `config.py` - Configuration and utilities
+- `law_embeddings.npy` - Precomputed embeddings (384-dim vectors)
+- `law_meta.json` - Metadata for legal articles
+- `conversation_contexts.json` - Context tracking storage
+
+## Installation (Self-Hosted)
+
+```bash
+# Clone the model repository
+git clone https://huggingface.co/mugwaneza/mbaza-model
+cd mbaza-model
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Test locally
+python inference.py
+```
+
+## API Limits
+
+- **Free Tier**: ~30,000 requests/month
+- **Rate Limiting**: ~100 requests/hour (burst)
+- **Cold Start**: First request may take 10-30 seconds
+- **Warm**: Subsequent requests ~1-3 seconds
+
+For production with higher limits, consider:
+1. Upgrading to Hugging Face PRO ($9/month)
+2. Self-hosting with this model
+3. Using dedicated inference endpoints
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Citation
+
+```bibtex
+@misc{mbaza-legal-ai,
+  author = {Mugwaneza Manzi},
+  title = {Mbaza Legal AI: Multilingual Legal Assistant for Rwanda},
+  year = {2025},
+  publisher = {Hugging Face},
+  url = {https://huggingface.co/mugwaneza/mbaza-model}
+}
+```
+
+## Related Resources
+
+- **Demo Space**: https://huggingface.co/spaces/mugwaneza/mbaza
+- **GitHub**: https://github.com/MUGWANEZAMANZI/Model
+- **Documentation**: See DEPLOYMENT.md in repository
+
+## Contact
+
+For questions, issues, or collaboration:
+- Create an issue on the [GitHub repository](https://github.com/MUGWANEZAMANZI/Model)
+- Email: mugwaneza@example.com (replace with your email)
+
+---
+
+**Note**: This model is designed for informational purposes. Always consult with a qualified legal professional for official legal advice.

assistant.py

@@ -0,0 +1,199 @@
+from pathlib import Path
+import json
+import re
+from typing import Dict, Any, List, Optional
+import random
+
+import pandas as pd
+
+from retriever import get_retriever
+from config import KINYARWANDA_STOPWORDS, calculate_similarity_score
+
+ROOT = Path(__file__).parent
+CONTEXT_PATH = ROOT / 'conversation_contexts.json'
+
+
+class Assistant:
+    def __init__(self):
+        self.retriever = get_retriever()
+        # load datasets
+        self.laws = None
+        self.punishments = None
+        self.greetings = None
+        self.contexts: Dict[str, List[Dict[str, Any]]] = {}
+        self.intent_keywords = {
+            'greeting': ['mwaramutse', 'muraho', 'amakuru', 'bite', 'mwiriwe', 'urabeho', 'urakomeye', 'ndabona'],
+            'law': ['itegeko', 'ingingo', 'article', 'ingingo ya', 'itegeko rya', 'law', 'article', 'ingingo'],
+            'punishment': ['igihano', 'ibihano', 'ihazabu', 'igifungo', 'fine', 'imyaka', 'years', 'punishment']
+        }
+        self.load_datasets()
+        self._load_contexts()
+
+    def load_datasets(self):
+        # laws are loaded by retriever; ensure available
+        try:
+            if self.retriever.laws_df is None:
+                self.retriever.load_laws()
+            self.laws = self.retriever.laws_df
+        except Exception:
+            self.laws = None
+
+        # punishments fallback to penal_code.csv
+        ppath = ROOT / 'penal_code.csv'
+        if ppath.exists():
+            try:
+                self.punishments = pd.read_csv(ppath).fillna('')
+            except Exception:
+                self.punishments = None
+        else:
+            self.punishments = None
+
+        # greetings
+        gpath = ROOT / 'greetings.csv'
+        if gpath.exists():
+            try:
+                self.greetings = pd.read_csv(gpath).fillna('')
+            except Exception:
+                self.greetings = None
+        else:
+            # retriever uses greetings.csv or kin... so try retriever load
+            try:
+                self.greetings = self.retriever.greetings_df
+            except Exception:
+                self.greetings = None
+
+    def _load_contexts(self):
+        if CONTEXT_PATH.exists():
+            try:
+                with open(CONTEXT_PATH, 'r', encoding='utf-8') as f:
+                    self.contexts = json.load(f)
+            except Exception:
+                self.contexts = {}
+
+    def _save_contexts(self):
+        try:
+            with open(CONTEXT_PATH, 'w', encoding='utf-8') as f:
+                json.dump(self.contexts, f, ensure_ascii=False, indent=2)
+        except Exception:
+            pass
+
+    def tokenize(self, text: str) -> List[str]:
+        if not text:
+            return []
+        txt = str(text).lower()
+        # simple cleaning
+        txt = re.sub(r"[\r\n]+", " ", txt)
+        txt = re.sub(r"[^\w\s\u00C0-\u017F]", " ", txt)
+        toks = [t for t in txt.split() if t and t not in KINYARWANDA_STOPWORDS]
+        return toks
+
+    def detect_intent(self, text: str) -> str:
+        t = str(text).lower()
+        toks = set(self.tokenize(t))
+        # keyword scoring
+        scores = {k: 0 for k in self.intent_keywords}
+        for intent, keywords in self.intent_keywords.items():
+            for kw in keywords:
+                if kw in t or kw in toks:
+                    scores[intent] += 1
+
+        # greeting detection via retriever as fallback
+        if scores.get('greeting', 0) > 0:
+            return 'greeting'
+
+        # if punishment keywords present
+        if scores.get('punishment', 0) > 0:
+            return 'punishment'
+
+        if scores.get('law', 0) > 0:
+            return 'law'
+
+        # try to detect if users mention known law numbers or article numbers
+        if re.search(r'\bingingo\b|\bingingo ya\b|\barticle\b|\bitegeko\b', t):
+            return 'law'
+
+        # default unclear
+        return 'unclear'
+
+    def _update_context(self, user_id: str, entry: Dict[str, Any]):
+        self.contexts.setdefault(user_id, []).append(entry)
+        # keep only last 50
+        if len(self.contexts[user_id]) > 50:
+            self.contexts[user_id] = self.contexts[user_id][-50:]
+        self._save_contexts()
+
+    def handle_query(self, user_id: str, text: str) -> Dict[str, Any]:
+        # first, try language-aware greeting detection (this handles ky/en/fr greetings)
+        # record the raw user message
+        self._update_context(user_id, {'role': 'user', 'text': text})
+
+        try:
+            reply = self.retriever.detect_and_reply_greeting(text)
+        except Exception:
+            reply = None
+
+        if reply:
+            out = {'type': 'greeting', 'response': reply.get('response', ''), 'followup': reply.get('followup', '')}
+            # record assistant response
+            self._update_context(user_id, {'role': 'assistant', 'text': out})
+            return out
+
+        # no greeting detected, continue with intent detection
+        intent = self.detect_intent(text)
+        # update the last user message with intent information as well
+        self._update_context(user_id, {'role': 'user', 'text': text, 'intent': intent})
+
+        if intent == 'law':
+            # use retriever find_similar
+            try:
+                # ensure embeddings built
+                self.retriever.build_or_load_embeddings()
+                results = self.retriever.find_similar(text, top_k=1)
+            except Exception:
+                results = []
+
+            if results:
+                score, meta = results[0]
+                law_row = meta.get('row')
+                out = {'type': 'law', 'score': score, 'law': law_row}
+                self._update_context(user_id, {'role': 'assistant', 'text': out})
+                return out
+
+            return {'type': 'unclear', 'text': "I couldn't find a matching law. Can you be more specific?"}
+
+        if intent == 'punishment':
+            # use simple matching against penal_code.csv if available, otherwise use overlap scoring
+            if self.punishments is not None:
+                # score by overlap
+                best = None
+                best_score = 0.0
+                for _, row in self.punishments.iterrows():
+                    desc = ' '.join([str(row.get(c, '')) for c in row.index])
+                    s = calculate_similarity_score(text, desc)
+                    if s > best_score:
+                        best_score = s
+                        best = row.to_dict()
+
+                if best is not None and best_score > 0:
+                    out = {'type': 'punishment', 'score': best_score, 'punishment_row': best}
+                    self._update_context(user_id, {'role': 'assistant', 'text': out})
+                    return out
+
+            # fallback: return unclear
+            return {'type': 'unclear', 'text': "I couldn't find a matching punishment. Can you provide more detail?"}
+
+        # unclear
+        out = {'type': 'unclear', 'text': "Can you please try a legal question? I'm here to assist you."}
+        self._update_context(user_id, {'role': 'assistant', 'text': out})
+        return out
+
+
+# Singleton assistant
+_ASSISTANT: Optional[Assistant] = None
+
+
+def get_assistant() -> Assistant:
+    global _ASSISTANT
+    if _ASSISTANT is None:
+        _ASSISTANT = Assistant()
+    return _ASSISTANT

config.py

@@ -0,0 +1,340 @@
+"""
+Configuration and utility functions for Rwanda Legal NLP System
+"""
+
+import os
+import json
+import logging
+import pandas as pd
+from typing import Dict, Any
+from dataclasses import dataclass
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+@dataclass
+class ModelConfig:
+    """Configuration for model settings"""
+    model_name: str = "EleutherAI/gpt-j-6B"
+    max_length: int = 512
+    temperature: float = 0.7
+    top_p: float = 0.9
+    top_k: int = 50
+    do_sample: bool = True
+    num_return_sequences: int = 1
+
+@dataclass
+class TrainingConfig:
+    """Configuration for training settings"""
+    output_dir: str = "./trained_legal_model"
+    num_epochs: int = 3
+    batch_size: int = 2
+    learning_rate: float = 5e-5
+    warmup_steps: int = 500
+    save_steps: int = 1000
+    eval_steps: int = 1000
+    max_grad_norm: float = 1.0
+    gradient_accumulation_steps: int = 4
+    weight_decay: float = 0.01
+
+@dataclass
+class DataConfig:
+    """Configuration for data processing"""
+    dataset_path: str = "dataset-all.csv"
+    max_text_length: int = 512
+    test_size: float = 0.1
+    random_state: int = 42
+
+class ConfigManager:
+    """Manage configuration for the legal NLP system"""
+    
+    def __init__(self, config_path: str = "config.json"):
+        self.config_path = config_path
+        self.model_config = ModelConfig()
+        self.training_config = TrainingConfig()
+        self.data_config = DataConfig()
+        
+        self.load_config()
+    
+    def load_config(self):
+        """Load configuration from JSON file if exists"""
+        if os.path.exists(self.config_path):
+            try:
+                with open(self.config_path, 'r') as f:
+                    config_data = json.load(f)
+                
+                # Update configurations
+                if 'model' in config_data:
+                    for key, value in config_data['model'].items():
+                        if hasattr(self.model_config, key):
+                            setattr(self.model_config, key, value)
+                
+                if 'training' in config_data:
+                    for key, value in config_data['training'].items():
+                        if hasattr(self.training_config, key):
+                            setattr(self.training_config, key, value)
+                
+                if 'data' in config_data:
+                    for key, value in config_data['data'].items():
+                        if hasattr(self.data_config, key):
+                            setattr(self.data_config, key, value)
+                
+                logging.info(f"Configuration loaded from {self.config_path}")
+                
+            except Exception as e:
+                logging.warning(f"Could not load config from {self.config_path}: {e}")
+    
+    def save_config(self):
+        """Save current configuration to JSON file"""
+        config_data = {
+            'model': self.model_config.__dict__,
+            'training': self.training_config.__dict__,
+            'data': self.data_config.__dict__
+        }
+        
+        try:
+            with open(self.config_path, 'w') as f:
+                json.dump(config_data, f, indent=2)
+            
+            logging.info(f"Configuration saved to {self.config_path}")
+            
+        except Exception as e:
+            logging.error(f"Could not save config to {self.config_path}: {e}")
+
+# Kinyarwanda language utilities
+KINYARWANDA_STOPWORDS = {
+    'ni', 'na', 'ku', 'mu', 'nk', 'no', 'cyangwa', 'ariko', 'naho', 'none',
+    'kandi', 'rero', 'ubwo', 'uko', 'ubu', 'aha', 'aho', 'iyo', 'ese',
+    'nta', 'nti', 'nte', 'nto', 'ntu', 'ntw', 'aba', 'ari', 'hari',
+    'kuri', 'muri', 'buri', 'abantu', 'umuntu', 'ibintu', 'ikintu'
+}
+
+# Kinyarwanda legal terminology
+KINYARWANDA_LEGAL_TERMS = {
+    'gusambanya': 'sexual defilement',
+    'kwiba': 'theft',
+    'gukoresha_imbaraga': 'use of force/violence', 
+    'kwinjira': 'enter/trespass',
+    'kwica': 'kill/murder',
+    'gukubita': 'assault/beat',
+    'uburiganya': 'fraud/deception',
+    'ubuhemu': 'embezzlement',
+    'igifungo': 'imprisonment',
+    'ihazabu': 'fine',
+    'igihano': 'punishment',
+    'ingingo': 'article',
+    'itegeko': 'law',
+    'umwana': 'child',
+    'imyaka': 'years',
+    'amezi': 'months',
+    'burundu': 'life (imprisonment)',
+    'gahato': 'force/violence',
+    'imibonano_mpuzabitsina': 'sexual intercourse',
+    'inyamaswa': 'animals',
+    'rugo': 'home/house'
+}
+
+def clean_kinyarwanda_text(text: str) -> str:
+    """Clean and normalize Kinyarwanda text"""
+    import re
+    
+    if not text or pd.isna(text):
+        return ""
+    
+    text = str(text)
+    
+    # Remove extra whitespace
+    text = re.sub(r'\s+', ' ', text)
+    
+    # Keep Kinyarwanda specific characters
+    text = re.sub(r'[^\w\s\-\.\,\;\:\!\?\'\"\u00C0-\u017F]', '', text)
+    
+    # Remove common noise patterns
+    text = re.sub(r'\b[0-9]+\b', ' NUMBER ', text)
+    text = re.sub(r'\bFRW\s*[0-9,\.]+\b', ' AMOUNT ', text)
+    text = re.sub(r'\b[0-9]+-[0-9]+\b', ' RANGE ', text)
+    
+    return text.strip()
+
+def extract_keywords_kinyarwanda(text: str, max_keywords: int = 10) -> list:
+    """Extract keywords from Kinyarwanda text"""
+    if not text:
+        return []
+    
+    # Simple keyword extraction
+    words = clean_kinyarwanda_text(text).lower().split()
+    
+    # Filter out stopwords and short words
+    keywords = [
+        word for word in words 
+        if len(word) > 2 and word not in KINYARWANDA_STOPWORDS
+    ]
+    
+    # Count frequency and return most common
+    from collections import Counter
+    word_counts = Counter(keywords)
+    
+    return [word for word, count in word_counts.most_common(max_keywords)]
+
+# Legal category mappings with Kinyarwanda terms
+LEGAL_CATEGORIES = {
+    'sexual_offence': {
+        'english': ['sexual', 'rape', 'assault', 'child', 'defilement'],
+        'kinyarwanda': ['gukoresha', 'gusambanya', 'igitsina', 'umwana', 'imibonano']
+    },
+    'theft': {
+        'english': ['theft', 'robbery', 'stealing', 'property'],
+        'kinyarwanda': ['kwiba', 'gufata', 'umutungo', 'imbaraga']
+    },
+    'privacy': {
+        'english': ['privacy', 'domicile', 'recording', 'entry'],
+        'kinyarwanda': ['kwinjira', 'kumviriza', 'rugo', 'ubuzima_bwite']
+    },
+    'morality': {
+        'english': ['adultery', 'bigamy', 'concubinage', 'marriage'],
+        'kinyarwanda': ['ubusambanyi', 'ubushoreke', 'gushyingirwa', 'guta_urugo']
+    },
+    'violence': {
+        'english': ['violence', 'murder', 'genocide', 'torture', 'assault'],
+        'kinyarwanda': ['kwica', 'gukubita', 'jenoside', 'ihohotera', 'imbaraga']
+    },
+    'fraud': {
+        'english': ['fraud', 'forgery', 'deception', 'embezzlement'],
+        'kinyarwanda': ['uburiganya', 'kwigana', 'ubuhemu', 'kwibeshya']
+    }
+}
+
+def categorize_case(description: str) -> str:
+    """Categorize a case based on description keywords (English and Kinyarwanda)"""
+    if not description:
+        return "unknown"
+    
+    description_lower = description.lower()
+    
+    category_scores = {}
+    
+    for category, terms in LEGAL_CATEGORIES.items():
+        score = 0
+        # Check English terms
+        for keyword in terms['english']:
+            if keyword in description_lower:
+                score += 2
+        
+        # Check Kinyarwanda terms  
+        for keyword in terms['kinyarwanda']:
+            if keyword in description_lower:
+                score += 3  # Higher weight for Kinyarwanda terms
+        
+        if score > 0:
+            category_scores[category] = score
+    
+    if category_scores:
+        return max(category_scores, key=category_scores.get)
+    else:
+        return "general"
+
+# Evaluation metrics
+def calculate_similarity_score(text1: str, text2: str) -> float:
+    """Calculate simple similarity score between two texts"""
+    if not text1 or not text2:
+        return 0.0
+    
+    words1 = set(clean_kinyarwanda_text(text1).lower().split())
+    words2 = set(clean_kinyarwanda_text(text2).lower().split())
+    
+    if not words1 or not words2:
+        return 0.0
+    
+    intersection = len(words1.intersection(words2))
+    union = len(words1.union(words2))
+    
+    return intersection / union if union > 0 else 0.0
+
+# Utility functions
+def save_predictions(predictions: list, output_path: str):
+    """Save predictions to file"""
+    try:
+        with open(output_path, 'w', encoding='utf-8') as f:
+            json.dump(predictions, f, indent=2, ensure_ascii=False)
+        
+        logging.info(f"Predictions saved to {output_path}")
+        
+    except Exception as e:
+        logging.error(f"Could not save predictions: {e}")
+
+def load_predictions(input_path: str) -> list:
+    """Load predictions from file"""
+    try:
+        with open(input_path, 'r', encoding='utf-8') as f:
+            predictions = json.load(f)
+        
+        logging.info(f"Predictions loaded from {input_path}")
+        return predictions
+        
+    except Exception as e:
+        logging.error(f"Could not load predictions: {e}")
+        return []
+
+def format_punishment(punishment: str) -> dict:
+    """Parse and format punishment information"""
+    if not punishment or pd.isna(punishment):
+        return {"type": "unknown", "details": ""}
+    
+    punishment = str(punishment).lower()
+    
+    result = {
+        "type": "unknown",
+        "imprisonment": None,
+        "fine": None,
+        "community_service": None,
+        "details": punishment
+    }
+    
+    # Extract imprisonment
+    import re
+    
+    # Years
+    year_pattern = r'(\d+)(?:-(\d+))?\s*(?:years?|imyaka)'
+    year_match = re.search(year_pattern, punishment)
+    if year_match:
+        min_years = int(year_match.group(1))
+        max_years = int(year_match.group(2)) if year_match.group(2) else min_years
+        result["imprisonment"] = f"{min_years}-{max_years} years"
+        result["type"] = "imprisonment"
+    
+    # Life imprisonment
+    if any(term in punishment for term in ['life', 'burundu', 'cya burundu']):
+        result["imprisonment"] = "Life imprisonment"
+        result["type"] = "life_imprisonment"
+    
+    # Fine amounts
+    fine_pattern = r'frw\s*([0-9,\.]+)(?:\s*-\s*([0-9,\.]+))?'
+    fine_match = re.search(fine_pattern, punishment)
+    if fine_match:
+        min_fine = fine_match.group(1)
+        max_fine = fine_match.group(2) if fine_match.group(2) else min_fine
+        result["fine"] = f"FRW {min_fine}-{max_fine}"
+    
+    # Community service
+    if 'community service' in punishment or 'inyungu rusange' in punishment:
+        result["community_service"] = "Yes"
+    
+    return result
+
+# Default configuration instance
+config_manager = ConfigManager()
+
+if __name__ == "__main__":
+    # Test utilities
+    sample_text = "Umuntu yakoreye umwana igikorwa gishingiye ku gitsina"
+    
+    print("Sample text:", sample_text)
+    print("Cleaned:", clean_kinyarwanda_text(sample_text))
+    print("Keywords:", extract_keywords_kinyarwanda(sample_text))
+    print("Category:", categorize_case(sample_text))
+    
+    sample_punishment = "Igifungo cy'imyaka 10-15 + ihazabu FRW 1,000,000-2,000,000"
+    print("Formatted punishment:", format_punishment(sample_punishment))

greetings.csv

@@ -0,0 +1,26 @@
+greeting,response,followup,greeting_en,response_en,followup_en,greeting_fr,response_fr,followup_fr
+Mwaramutse,"Mwaramutse neza, amakuru yawe? (Ndaganira gusa mu Kinyarwanda)","Ndishimye ko umeze neza, mbwira icyo ngufasha mu mategeko cg urubanza witegura. (Ndaganira gusa mu Kinyarwanda)","Good morning","Good morning, how are you? (I only speak Kinyarwanda)","I'm glad you're well, tell me how I can help you with legal matters or your upcoming case. (I only speak Kinyarwanda)","Bonjour","Bonjour, comment ça va ? (Je ne parle que le kinyarwanda)","Je suis content que tu ailles bien, dis-moi comment je peux t'aider avec des questions juridiques ou ton prochain procès. (Je ne parle que le kinyarwanda)"
+Bite,"Ni byiza, uraho nawe? (Ndaganira gusa mu Kinyarwanda)","Ndishimye ko umeze neza, hari ikibazo cy'amategeko ushaka ko tuganiraho? (Ndaganira gusa mu Kinyarwanda)","Hi","I'm good, how about you? (I only speak Kinyarwanda)","I'm glad you're well, is there a legal issue you'd like to discuss? (I only speak Kinyarwanda)","Salut","Je vais bien, et toi ? (Je ne parle que le kinyarwanda)","Je suis content que tu ailles bien, y a-t-il un problème juridique dont tu veux parler ? (Je ne parle que le kinyarwanda)"
+Amakuru,"Ni meza cyane, wowe se? (Ndaganira gusa mu Kinyarwanda)","Ndanezerewe ko wowe nawe umeze neza, hari icyo wifuza kumenya ku mategeko? (Ndaganira gusa mu Kinyarwanda)","How are you?","I'm very well, and you? (I only speak Kinyarwanda)","I'm happy that you are also well, is there anything you want to know about the law? (I only speak Kinyarwanda)","Comment vas-tu ?","Je vais très bien, et toi ? (Je ne parle que le kinyarwanda)","Je suis heureux que tu ailles bien aussi, y a-t-il quelque chose que tu veux savoir sur la loi ? (Je ne parle que le kinyarwanda)"
+Bite se,"Ni fresh, uraho neza!","Ndishimye ko umeze neza, hari icyo wifuza kumenya cyangwa kugisha inama?","Hey there","I'm great, how are you?","I'm glad you're well, is there anything you want to know or ask advice about?","Coucou","Je vais super bien, comment vas-tu ?","Je suis content que tu ailles bien, y a-t-il quelque chose que tu veux savoir ou demander un conseil ?"
+Mwiriwe,"Mwiriwe neza, amakuru yawe?","Ndishimye ko umeze neza, mbwira icyo ngufasha mu mategeko cg urubanza witegura.","Good afternoon","Good afternoon, how are you?","I'm glad you're well, tell me how I can help you with legal matters or your upcoming case.","Bon après-midi","Bon après-midi, comment ça va ?","Je suis content que tu ailles bien, dis-moi comment je peux t'aider avec des questions juridiques ou ton prochain procès."
+Muraho,"Muraho neza, uraho ute?","Ndishimye ko umeze neza, hari ikibazo cy'amategeko ushaka ko tuganiraho?","Hello","Hello, how are you?","I'm glad you're well, is there a legal issue you'd like to discuss?","Bonjour","Bonjour, comment vas-tu ?","Je suis content que tu ailles bien, y a-t-il un problème juridique dont tu veux parler ?"
+Umeze ute,"Meze neza cyane, urakoze kubaza.","Ndanezerewe ko umeze neza, hari icyo wifuza kumenya ku mategeko?","How are you feeling?","I'm very well, thank you for asking.","I'm happy that you are well, is there anything you want to know about the law?","Comment te sens-tu ?","Je vais très bien, merci de demander.","Je suis heureux que tu ailles bien, y a-t-il quelque chose que tu veux savoir sur la loi ?"
+Urakomeye,"Ndakomeye, nawe uraho neza?","Ndishimye ko umeze neza, hari icyo wifuza kumenya cyangwa kugisha inama?","Are you strong?","I'm strong, how are you?","I'm glad you're well, is there anything you want to know or ask advice about?","Tu es fort ?","Je suis fort, et toi comment vas-tu ?","Je suis content que tu ailles bien, y a-t-il quelque chose que tu veux savoir ou demander un conseil ?"
+Urabeho,"Urabeho, tuzabonana ubutaha.","Niba hari ikibazo cy'amategeko uzagaruke tuganireho.","Goodbye","Goodbye, see you next time.","If you have a legal issue, come back and we'll discuss it.","Au revoir","Au revoir, à la prochaine.","Si tu as un problème juridique, reviens et nous en discuterons."
+Ndagushimiye,"Nta kibazo, nanjye ndagushimiye.","Niba hari ikindi ushaka kumenya, ntuzazuyaze kumbaza.","Thank you","No problem, thank you too.","If there's anything else you want to know, don't hesitate to ask.","Merci","Pas de problème, merci à toi aussi.","Si tu veux savoir autre chose, n'hésite pas à demander."
+Urakoze,"Urakoze nawe, ni byiza kugufasha.","Niba hari ikindi kibazo cy'amategeko, ndahari kugufasha.","Thanks","Thanks to you too, it's good to help you.","If you have any other legal questions, I'm here to help.","Merci","Merci à toi aussi, c'est un plaisir de t'aider.","Si tu as d'autres questions juridiques, je suis là pour t'aider."
+Wiriwe,"Wiriwe neza, tugire umunsi mwiza.","Niba hari icyo wifuza kumenya, ndahari kugufasha.","Good evening","Good evening, have a nice day.","If there's anything you want to know, I'm here to help.","Bonsoir","Bonsoir, passe une bonne journée.","Si tu veux savoir quelque chose, je suis là pour t'aider."
+Ijoro ryiza,"Ijoro ryiza nawe, uryame rwose.","Niba hari ikibazo cy'amategeko, uzambwire ejo.","Good night","Good night to you too, sleep well.","If you have a legal issue, let me know tomorrow.","Bonne nuit","Bonne nuit à toi aussi, dors bien.","Si tu as un problème juridique, dis-le-moi demain."
+Naho,"Ni byiza cyane, uraho neza!","Ndishimye ko umeze neza, hari icyo wifuza kumenya cyangwa kugisha inama?","Hey","That's great, how are you?","I'm glad you're well, is there anything you want to know or ask advice about?","Salut","C'est super, comment vas-tu ?","Je suis content que tu ailles bien, y a-t-il quelque chose que tu veux savoir ou demander un conseil ?"
+Murabeho,"Murabeho, mukomeze kugira umugisha.","Niba hari ikibazo cy'amategeko uzagaruke tuganireho.","Farewell","Farewell, may you continue to be blessed.","If you have a legal issue, come back and we'll discuss it.","Adieu","Adieu, que tu continues à être béni.","Si tu as un problème juridique, reviens et nous en discuterons."
+Ndishimye ko umeze neza, mbwira icyo ngufasha mu mategeko cg urubanza witegura.,"Nditeguye kugufasha, sobanura ikibazo cyawe.","Wakenera ubundi bufasha bw'amategeko?","I'm glad you're well, tell me how I can help you with legal matters or your upcoming case.","I'm ready to help you, explain your issue.","Would you need any other legal assistance?","Je suis content que tu ailles bien, dis-moi comment je peux t'aider avec des questions juridiques ou ton prochain procès.","Je suis prêt à t'aider, explique ton problème.","Aurais-tu besoin d'une autre assistance juridique ?"
+Ndishimye ko umeze neza, hari ikibazo cy'amategeko ushaka ko tuganiraho?,"Mbwira ikibazo cyawe, ndagufasha uko nshoboye.","Hari ibindi wifuza kumenya?","I'm glad you're well, is there a legal issue you'd like to discuss?","Tell me your issue, I'll help as much as I can.","Is there anything else you want to know?","Je suis content que tu ailles bien, y a-t-il un problème juridique dont tu veux parler ?","Dis-moi ton problème, je t'aiderai autant que possible.","Y a-t-il autre chose que tu veux savoir ?"
+Ndanezerewe ko wowe nawe umeze neza, hari icyo wifuza kumenya ku mategeko?,"Niba hari ikibazo cyihariye, nyibwira.","Ndashobora kugufasha no mu bindi bibazo by'amategeko.","I'm happy that you are also well, is there anything you want to know about the law?","If you have a specific issue, tell me.","I can also help you with other legal issues.","Je suis heureux que tu ailles bien aussi, y a-t-il quelque chose que tu veux savoir sur la loi ?","Si tu as un problème spécifique, dis-le-moi.","Je peux aussi t'aider avec d'autres questions juridiques."
+Ndishimye ko umeze neza, hari icyo wifuza kumenya cyangwa kugisha inama?,"Sobanura ikibazo cyawe, nditeguye kugufasha.","Hari indi nama ushaka?","I'm glad you're well, is there anything you want to know or ask advice about?","Explain your issue, I'm ready to help.","Do you want any other advice?","Je suis content que tu ailles bien, y a-t-il quelque chose que tu veux savoir ou demander un conseil ?","Explique ton problème, je suis prêt à t'aider.","Veux-tu un autre conseil ?"
+Ndanezerewe ko umeze neza, hari icyo wifuza kumenya ku mategeko?,"Mbwira ikibazo cyawe cy'amategeko.","Niba hari ibindi bibazo, ndahari.","I'm happy that you are well, is there anything you want to know about the law?","Tell me your legal issue.","If there are other questions, I'm here.","Je suis heureux que tu ailles bien, y a-t-il quelque chose que tu veux savoir sur la loi ?","Dis-moi ton problème juridique.","S'il y a d'autres questions, je suis là."
+Niba hari ikibazo cy'amategeko uzagaruke tuganireho.,"Uzanyandikire igihe cyose ukeneye ubufasha.","Igihe cyose ukeneye inama, ndahari.","If you have a legal issue, come back and we'll discuss it.","Write to me anytime you need help.","Whenever you need advice, I'm here.","Si tu as un problème juridique, reviens et nous en discuterons.","Écris-moi quand tu as besoin d'aide.","Quand tu as besoin de conseils, je suis là."
+Niba hari ikindi ushaka kumenya, ntuzazuyaze kumbaza.,"Nditeguye kugufasha igihe cyose.","Wakenera ubundi bufasha?","If there's anything else you want to know, don't hesitate to ask.","I'm ready to help you anytime.","Would you need any other assistance?","Si tu veux savoir autre chose, n'hésite pas à demander.","Je suis prêt à t'aider à tout moment.","Aurais-tu besoin d'une autre assistance ?"
+Niba hari ikindi kibazo cy'amategeko, ndahari kugufasha.,"Mbwira ikibazo cyawe igihe cyose.","Ndashobora kugufasha no mu bindi.","If you have any other legal questions, I'm here to help.","Tell me your issue anytime.","I can also help you with other things.","Si tu as d'autres questions juridiques, je suis là pour t'aider.","Dis-moi ton problème à tout moment.","Je peux aussi t'aider avec d'autres choses."
+Niba hari icyo wifuza kumenya, ndahari kugufasha.,"Sobanura icyo wifuza kumenya.","Nditeguye kugufasha igihe cyose.","If there's anything you want to know, I'm here to help.","Explain what you want to know.","I'm ready to help you anytime.","Si tu veux savoir quelque chose, je suis là pour t'aider.","Explique ce que tu veux savoir.","Je suis prêt à t'aider à tout moment."
+Niba hari ikibazo cy'amategeko, uzambwire ejo.,"Uzanyandikire igihe cyose ukeneye ubufasha.","Ndahari igihe cyose ukeneye inama.","If you have a legal issue, let me know tomorrow.","Write to me anytime you need help.","I'm here whenever you need advice.","Si tu as un problème juridique, dis-le-moi demain.","Écris-moi quand tu as besoin d'aide.","Je suis là chaque fois que tu as besoin de conseils."

inference.py

@@ -0,0 +1,73 @@
+"""
+Hugging Face Inference API endpoint for mbaza-model
+This file exposes the model for API calls via HF Inference API.
+"""
+from typing import Dict, List, Any
+from assistant import get_assistant
+
+# Initialize the assistant once
+assistant = get_assistant()
+
+
+def model(inputs: List[str]) -> Dict[str, Any]:
+    """
+    Main inference function called by Hugging Face Inference API.
+    
+    Args:
+        inputs: List of input strings (prompts/queries)
+        
+    Returns:
+        Dict with model response
+    """
+    if not inputs or not isinstance(inputs, list):
+        return {"error": "Invalid input format. Expected list of strings."}
+    
+    prompt = inputs[0]
+    user_id = inputs[1] if len(inputs) > 1 else "api_user"
+    
+    try:
+        result = assistant.handle_query(user_id, prompt)
+        return result
+    except Exception as e:
+        return {
+            "error": f"Processing failed: {str(e)}",
+            "text": "An error occurred while processing your request."
+        }
+
+
+def predict(prompt: str, user_id: str = "api_user") -> Dict[str, Any]:
+    """
+    Alternative prediction function with explicit parameters.
+    
+    Args:
+        prompt: User query or greeting
+        user_id: Optional user identifier for context tracking
+        
+    Returns:
+        Dict with response, intent, and any matched data
+    """
+    try:
+        result = assistant.handle_query(user_id, prompt)
+        return result
+    except Exception as e:
+        return {
+            "error": f"Processing failed: {str(e)}",
+            "text": "An error occurred while processing your request."
+        }
+
+
+# For testing locally
+if __name__ == "__main__":
+    test_queries = [
+        "Mwaramutse neza",
+        "Ibihano by'ubujura ni ibihe?",
+        "Kwinjira aho umuntu atuye bitemewe namategeko",
+        "What are the laws about corruption?"
+    ]
+    
+    print("Testing inference.py locally...\n")
+    for query in test_queries:
+        print(f"Query: {query}")
+        response = model([query])
+        print(f"Response: {response.get('text', response)}")
+        print("-" * 80)

law_embeddings.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e537738aac9aa323758cde5c61b7ab843ff3b1ab6189a5e63b405d11574ec432
+size 3090560

requirements.txt

@@ -0,0 +1,7 @@
+pandas
+sentence-transformers
+torch
+nltk
+flask
+gunicorn
+gradio

retriever.py

@@ -0,0 +1,207 @@
+from pathlib import Path
+import pandas as pd
+import numpy as np
+import os
+import json
+import random
+from typing import List, Dict, Any, Tuple
+
+try:
+    from sentence_transformers import SentenceTransformer
+except Exception:
+    SentenceTransformer = None
+
+ROOT = Path(__file__).parent
+MODEL_NAME = 'all-MiniLM-L6-v2'
+EMBED_PATH = ROOT / 'law_embeddings.npy'
+META_PATH = ROOT / 'law_meta.json'
+
+
+def _combine_law_text(row: pd.Series) -> str:
+    parts = []
+    for col in ['Law-Name', 'Article-Description', 'Punishment', 'Category', 'Chapter', 'Article-Number']:
+        if col in row and pd.notna(row[col]):
+            parts.append(str(row[col]))
+    return ' '.join(parts)
+
+
+class LawRetriever:
+    def __init__(self, model_name: str = MODEL_NAME):
+        self.model_name = model_name
+        self.model = None
+        self.laws_df: pd.DataFrame | None = None
+        self.embeddings: np.ndarray | None = None
+        self.meta: List[dict] = []
+        self.greetings_df: pd.DataFrame | None = None
+
+    def ensure_model(self):
+        if self.model is None:
+            if SentenceTransformer is None:
+                raise RuntimeError('sentence-transformers not available in environment')
+            self.model = SentenceTransformer(self.model_name)
+
+    def load_laws(self, laws_path: Path | str = None):
+        path = Path(laws_path) if laws_path else ROOT / 'dataset-all.csv'
+        if not path.exists():
+            raise FileNotFoundError(f'Laws CSV not found at {path}')
+        df = pd.read_csv(path)
+        # ensure consistent columns
+        df = df.fillna('')
+        self.laws_df = df
+        # build metadata
+        self.meta = []
+        for i, row in df.iterrows():
+            combined = _combine_law_text(row)
+            self.meta.append({'index': int(i), 'text': combined})
+        return df
+
+    def build_or_load_embeddings(self, force: bool = False):
+        # If embeddings exist and not forced, load them
+        if EMBED_PATH.exists() and META_PATH.exists() and not force:
+            try:
+                self.embeddings = np.load(EMBED_PATH)
+                with open(META_PATH, 'r', encoding='utf-8') as f:
+                    self.meta = json.load(f)
+                # ensure laws_df exists
+                if self.laws_df is None:
+                    self.load_laws()
+                return self.embeddings
+            except Exception:
+                # fall through to rebuild
+                pass
+
+        # Build embeddings
+        if self.laws_df is None:
+            self.load_laws()
+
+        self.ensure_model()
+        texts = [m['text'] for m in self.meta]
+        if not texts:
+            self.embeddings = np.zeros((0, 384), dtype=np.float32)
+        else:
+            emb = self.model.encode(texts, convert_to_numpy=True, show_progress_bar=True)
+            # normalize
+            norms = np.linalg.norm(emb, axis=1, keepdims=True)
+            norms[norms == 0] = 1
+            emb = emb / norms
+            self.embeddings = emb.astype(np.float32)
+            np.save(EMBED_PATH, self.embeddings)
+            with open(META_PATH, 'w', encoding='utf-8') as f:
+                json.dump(self.meta, f, ensure_ascii=False)
+
+        return self.embeddings
+
+    def find_similar(self, query: str, top_k: int = 1) -> List[Tuple[float, dict]]:
+        if self.embeddings is None:
+            self.build_or_load_embeddings()
+        self.ensure_model()
+        q_emb = self.model.encode([query], convert_to_numpy=True)
+        q_emb = q_emb / np.linalg.norm(q_emb, axis=1, keepdims=True)
+        sims = (self.embeddings @ q_emb[0]).astype(float)
+        # get top_k indices
+        idx = np.argsort(-sims)[:top_k]
+        results = []
+        for i in idx:
+            score = float(sims[i])
+            meta = self.meta[i].copy()
+            meta['score'] = score
+            # attach original row (if available)
+            if self.laws_df is not None and int(meta['index']) in self.laws_df.index:
+                row = self.laws_df.loc[int(meta['index'])].to_dict()
+                meta['row'] = row
+            results.append((score, meta))
+        return results
+
+    def load_greetings(self, path: Path | str = None):
+        p = Path(path) if path else ROOT / 'greetings.csv'
+        if not p.exists():
+            raise FileNotFoundError(f'Greetings CSV not found at {p}')
+        try:
+            df = pd.read_csv(p)
+        except Exception:
+            # sometimes the CSV has irregular quoting/commas; try a more tolerant parser
+            try:
+                df = pd.read_csv(p, engine='python', on_bad_lines='skip')
+            except Exception:
+                # final fallback: read as plain text and attempt a crude split
+                text = p.read_text(encoding='utf-8', errors='ignore')
+                # attempt to split lines and parse with first line as header
+                lines = [l for l in text.splitlines() if l.strip()]
+                if not lines:
+                    raise
+                header = [h.strip() for h in lines[0].split(',')]
+                records = []
+                for ln in lines[1:]:
+                    parts = [c.strip() for c in ln.split(',')]
+                    # pad/truncate to header length
+                    if len(parts) < len(header):
+                        parts += [''] * (len(header) - len(parts))
+                    parts = parts[:len(header)]
+                    records.append(dict(zip(header, parts)))
+                df = pd.DataFrame.from_records(records)
+
+        self.greetings_df = df.fillna('')
+        return self.greetings_df
+
+    def detect_and_reply_greeting(self, text: str) -> dict | None:
+        # Load greetings if needed
+        if self.greetings_df is None:
+            try:
+                self.load_greetings()
+            except FileNotFoundError:
+                return None
+        t = str(text).lower().strip()
+
+        # Check exact/substring matches across language columns and prefer language-specific response
+        tokens = set(t.split())
+
+        # 1) direct matches preferring Kinyarwanda, then English, then French
+        for lang_suffix in ['', '_en', '_fr']:
+            gcol = f'greeting{lang_suffix}'
+            rcol = f'response{lang_suffix}'
+            fcol = f'followup{lang_suffix}'
+            for _, row in self.greetings_df.iterrows():
+                gval = str(row.get(gcol, '')).strip()
+                if not gval:
+                    continue
+                gval_l = gval.lower()
+                if gval_l == t or gval_l in t or t in gval_l:
+                    response = row.get(rcol) or row.get('response') or row.get('response_en') or row.get('response_fr') or ''
+                    followup = row.get(fcol) or row.get('followup') or row.get('followup_en') or row.get('followup_fr') or ''
+                    return {'response': response, 'followup': followup}
+
+        # 2) token overlap fallback: collect candidates with token overlap across languages
+        candidates = []
+        for _, row in self.greetings_df.iterrows():
+            for lang_suffix in ['', '_en', '_fr']:
+                gcol = f'greeting{lang_suffix}'
+                gval = str(row.get(gcol, '')).strip().lower()
+                if not gval:
+                    continue
+                if any(tok in gval.split() for tok in tokens):
+                    candidates.append((row, lang_suffix))
+
+        if candidates:
+            row, lang_suffix = random.choice(candidates)
+            rcol = f'response{lang_suffix}'
+            fcol = f'followup{lang_suffix}'
+            response = row.get(rcol) or row.get('response') or row.get('response_en') or row.get('response_fr') or ''
+            followup = row.get(fcol) or row.get('followup') or row.get('followup_en') or row.get('followup_fr') or ''
+            return {'response': response, 'followup': followup}
+
+        return None
+
+
+# Provide a singleton retriever for the server to use
+_RETRIEVER: LawRetriever | None = None
+
+
+def get_retriever() -> LawRetriever:
+    global _RETRIEVER
+    if _RETRIEVER is None:
+        _RETRIEVER = LawRetriever()
+        try:
+            _RETRIEVER.load_laws()
+        except FileNotFoundError:
+            pass
+    return _RETRIEVER