Upload folder using huggingface_hub

README.md

@@ -1,13 +1,33 @@
 ---
-title: Rieko
-emoji: 🚀
-colorFrom: gray
-colorTo: green
+title: RiekoLM Dholuo AI Assistant
+emoji: 🦁
+colorFrom: yellow
+colorTo: red
 sdk: gradio
-sdk_version: 6.30.0
-python_version: '3.12'
+sdk_version: 5.20.0
 app_file: app.py
 pinned: false
+short_description: Gemma 3 1B Dholuo conversational & translation AI
+models:
+  - google/gemma-3-1b-pt
+  - Bennerdo/rieko
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# RiekoLM: Gemma 3 1B for Dholuo 🦁
+
+Interactive demo for **RiekoLM** ([`Bennerdo/rieko`](https://huggingface.co/Bennerdo/rieko)), an open-source Dholuo (Luo language of Kenya and Tanzania) AI assistant fine-tuned on Google's **Gemma 3 1B** (`google/gemma-3-1b-pt`) with two-stage QLoRA.
+
+### 🌟 Key Capabilities
+- 💬 **Conversational Dholuo**: Natural multi-turn dialogue in Dholuo with native idioms and cultural expressions.
+- 🔄 **Bidirectional Translation**: High-quality translation between English ↔ Dholuo and Swahili → Dholuo.
+- 📖 **Sigana & Cultural Knowledge**: Luo folklore (e.g., *Luanda Magere*, *Gor Mahia*), proverbs (*Ngeche*), and regional traditions around Lake Victoria (*Nam Lolwe*).
+
+### 🛠️ Architecture & Training
+- **Base Model**: [`google/gemma-3-1b-pt`](https://huggingface.co/google/gemma-3-1b-pt)
+- **Adapter**: [`Bennerdo/rieko`](https://huggingface.co/Bennerdo/rieko)
+- **Stage 1**: Continued Pre-Training (CPT) on cleaned Dholuo corpora (Bible, Wikipedia, Mafand dataset, local archives).
+- **Stage 2**: Supervised Fine-Tuning (SFT) on curated conversational instructions, folklore, and parallel translation pairs.
+- **Hardware**: ZeroGPU (`zero-a10g`).
+
+---
+Built with ❤️ for the Luo language community and African NLP preservation.

app.py

@@ -0,0 +1,226 @@
+try:
+    import spaces
+    has_spaces = True
+except ImportError:
+    has_spaces = False
+    class _MockSpaces:
+        def GPU(self, *args, **kwargs):
+            if len(args) == 1 and callable(args[0]):
+                return args[0]
+            def decorator(f):
+                return f
+            return decorator
+    spaces = _MockSpaces()
+
+import os
+from threading import Thread
+import gradio as gr
+import torch
+from peft import PeftModel
+from transformers import AutoModelForCausalLM, AutoTokenizer, TextIteratorStreamer
+
+BASE_MODEL_ID = "google/gemma-3-1b-pt"
+ADAPTER_ID = "Bennerdo/rieko"
+HF_TOKEN = os.environ.get("HF_TOKEN", None)
+
+print(f"Loading tokenizer from {ADAPTER_ID}...")
+tokenizer = AutoTokenizer.from_pretrained(ADAPTER_ID, token=HF_TOKEN)
+if tokenizer.pad_token_id is None:
+    tokenizer.pad_token_id = tokenizer.eos_token_id
+
+print(f"Loading base model from {BASE_MODEL_ID}...")
+device = "cuda" if torch.cuda.is_available() else "cpu"
+torch_dtype = torch.bfloat16 if torch.cuda.is_available() else torch.float32
+
+base_model = AutoModelForCausalLM.from_pretrained(
+    BASE_MODEL_ID,
+    torch_dtype=torch_dtype,
+    token=HF_TOKEN,
+)
+
+if torch.cuda.is_available():
+    base_model = base_model.to("cuda")
+
+print(f"Loading LoRA adapter from {ADAPTER_ID}...")
+model = PeftModel.from_pretrained(base_model, ADAPTER_ID)
+if torch.cuda.is_available():
+    model = model.to("cuda")
+
+try:
+    model = model.merge_and_unload()
+    print("Merged LoRA adapter into base model successfully.")
+except Exception as err:
+    print(f"Using PeftModel directly without merge: {err}")
+
+model.eval()
+print(f"Model ready on {device} ({torch_dtype})!")
+
+
+@spaces.GPU(duration=60)
+def respond(
+    message: str,
+    history: list[dict],
+    temperature: float = 0.3,
+    top_p: float = 0.9,
+    max_tokens: int = 384,
+    system_prompt: str = "",
+):
+    """Generate streaming conversational responses in Dholuo using RiekoLM.
+
+    Args:
+        message: The latest user prompt or query.
+        history: Prior messages formatted as [{'role': 'user'|'assistant', 'content': str}].
+        temperature: Sampling temperature (0.0 = deterministic, higher = creative).
+        top_p: Nucleus sampling probability cutoff.
+        max_tokens: Maximum number of new tokens to generate.
+        system_prompt: Optional background instruction or steering prompt.
+    """
+    messages = []
+    first_user_handled = False
+    sys_text = system_prompt.strip() if system_prompt else ""
+
+    for turn in history:
+        role = "assistant" if turn["role"] in ("assistant", "model") else "user"
+        content = turn["content"]
+        if role == "user" and not first_user_handled and sys_text:
+            content = f"[Instruction: {sys_text}]\n\n{content}"
+            first_user_handled = True
+        messages.append({"role": role, "content": content})
+
+    if not first_user_handled and sys_text:
+        current_content = f"[Instruction: {sys_text}]\n\n{message}"
+    else:
+        current_content = message
+
+    messages.append({"role": "user", "content": current_content})
+
+    prompt_text = tokenizer.apply_chat_template(
+        messages,
+        tokenize=False,
+        add_generation_prompt=True,
+    )
+    inputs = tokenizer(prompt_text, return_tensors="pt").to(model.device)
+
+    streamer = TextIteratorStreamer(tokenizer, skip_prompt=True, skip_special_tokens=True)
+    stop_tokens = [tokenizer.eos_token_id]
+    end_of_turn = tokenizer.convert_tokens_to_ids("<end_of_turn>")
+    if end_of_turn is not None and end_of_turn not in stop_tokens:
+        stop_tokens.append(end_of_turn)
+
+    generation_kwargs = dict(
+        input_ids=inputs["input_ids"],
+        attention_mask=inputs.get("attention_mask"),
+        max_new_tokens=max_tokens,
+        do_sample=temperature > 0,
+        temperature=max(temperature, 0.01) if temperature > 0 else 1.0,
+        top_p=top_p if temperature > 0 else 1.0,
+        repetition_penalty=1.15,
+        no_repeat_ngram_size=4,
+        eos_token_id=stop_tokens,
+        streamer=streamer,
+    )
+
+    thread = Thread(target=model.generate, kwargs=generation_kwargs)
+    thread.start()
+
+    partial_message = ""
+    for new_token in streamer:
+        clean_token = new_token.replace("<end_of_turn>", "").replace("<eos>", "").replace("<bos>", "")
+        partial_message += clean_token
+        yield partial_message
+
+    thread.join()
+
+
+custom_css = """
+.gradio-container {
+    max-width: 950px !important;
+    margin: 0 auto !important;
+}
+.header-badge {
+    display: inline-block;
+    padding: 3px 10px;
+    border-radius: 9999px;
+    font-size: 0.78rem;
+    font-weight: 600;
+    margin-right: 6px;
+    background: rgba(234, 179, 8, 0.15);
+    color: #eab308;
+    border: 1px solid rgba(234, 179, 8, 0.3);
+}
+.header-badge-gpu {
+    display: inline-block;
+    padding: 3px 10px;
+    border-radius: 9999px;
+    font-size: 0.78rem;
+    font-weight: 600;
+    margin-right: 6px;
+    background: rgba(34, 197, 94, 0.15);
+    color: #22c55e;
+    border: 1px solid rgba(34, 197, 94, 0.3);
+}
+"""
+
+theme = gr.themes.Soft(
+    primary_hue="amber",
+    secondary_hue="red",
+    neutral_hue="slate",
+)
+
+with gr.Blocks(theme=theme, css=custom_css, title="RiekoLM: Dholuo AI Assistant") as demo:
+    gr.HTML(
+        """
+        <div style="text-align: center; margin-top: 10px; margin-bottom: 16px;">
+            <h1 style="font-size: 2.2rem; font-weight: 800; margin-bottom: 6px;">
+                🦁 RiekoLM: Dholuo AI Assistant
+            </h1>
+            <p style="font-size: 1.05rem; opacity: 0.85; max-width: 650px; margin: 0 auto 12px auto;">
+                Interactive AI assistant fine-tuned on Google's <b>Gemma 3 1B</b> with two-stage QLoRA for fluent Dholuo conversation, translation, and cultural knowledge.
+            </p>
+            <div>
+                <span class="header-badge">Google Gemma 3 1B</span>
+                <span class="header-badge">Dholuo · Luo</span>
+                <span class="header-badge">English ↔ Dholuo</span>
+                <span class="header-badge">Swahili → Dholuo</span>
+                <span class="header-badge-gpu">⚡ ZeroGPU Accelerated</span>
+            </div>
+        </div>
+        """
+    )
+
+    gr.ChatInterface(
+        fn=respond,
+        type="messages",
+        examples=[
+            ["An iluonga ni Akinyi, in iluongi ni ng'a?", 0.3, 0.9, 384, ""],
+            ["Translate from English to Dholuo:\nGood morning, how was your night? I hope you rested well.", 0.2, 0.9, 384, ""],
+            ["Translate from Dholuo to English:\nEre kaka inyalo konyo joma nigi tho e dala?", 0.2, 0.9, 384, ""],
+            ["Lwanda Magere ne en ng'a e sigand Luo, kendo nyocha otho nang'o?", 0.4, 0.9, 384, ""],
+            ["Nyisa kaka inyalo pidho mbuta kod ngege e nam Lolwe.", 0.3, 0.9, 384, ""],
+            ["Tafsiri kwa Dholuo: Karibu nyumbani, tuketi tule chakula pamoja.", 0.2, 0.9, 384, ""],
+        ],
+        additional_inputs=[
+            gr.Slider(minimum=0.0, maximum=1.0, value=0.3, step=0.05, label="Temperature", info="Lower = more deterministic & factual, higher = creative"),
+            gr.Slider(minimum=0.1, maximum=1.0, value=0.9, step=0.05, label="Top-p", info="Nucleus sampling probability threshold"),
+            gr.Slider(minimum=64, maximum=512, value=384, step=32, label="Max New Tokens", info="Maximum generation length"),
+            gr.Textbox(value="", label="System / Cultural Steering (Optional)", placeholder="E.g., You are a wise Luo elder explaining traditions...", lines=1),
+        ],
+    )
+
+    with gr.Accordion("ℹ️ About RiekoLM & Research Details", open=False):
+        gr.Markdown(
+            """
+            ### Overview
+            **RiekoLM** is an open-source Dholuo (Luo language of Kenya and Tanzania) AI assistant.
+            It adapts Google's `google/gemma-3-1b-pt` using a two-stage QLoRA strategy:
+            1. **Continued Pre-Training (CPT)**: Trained across cleaned Dholuo texts (Bible, Wikipedia, Mafand dataset, local historical scripts).
+            2. **Supervised Fine-Tuning (SFT)**: Instruct-tuned on conversational interactions, cultural lore (*Sigendini*), and multi-lingual translation pairs.
+
+            - **Model Card & Weights**: [Bennerdo/rieko](https://huggingface.co/Bennerdo/rieko)
+            - **Base Architecture**: [google/gemma-3-1b-pt](https://huggingface.co/google/gemma-3-1b-pt)
+            - **License**: Gemma Terms of Use
+            """
+        )
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)

requirements.txt

@@ -0,0 +1,5 @@
+transformers>=4.50.0
+peft>=0.14.0
+accelerate
+sentencepiece
+protobuf