Finalize GenAI exam: simplify qabilah+q2, add q5 LangChain agent

README.md

@@ -15,8 +15,8 @@ You are interviewing to join the team that builds **agents like Cumin** — the
 
 1. Introduce yourself to the Arabic tech ecosystem (**Qabilah** + **Mortakaz**).
 2. Design a **memory module** for an agent like Cumin, and show how to use it.
-3. Plan how to **fine-tune an Arabic TTS or STT** model.
+3. Propose an **Arabic TTS or STT** model + dataset.
-4. Sign up to **Ghaymah** and **deploy a simple static website**.
+4. Sign up to **Ghaymah**, **deploy a static website**, and build a **LangChain agent** on Ghaymah's GenAI services.
 
 ## What we are evaluating
 
@@ -24,8 +24,9 @@ You are interviewing to join the team that builds **agents like Cumin** — the
 |---|---|
 | Arabic tech ecosystem awareness | Qabilah + Mortakaz tasks |
 | Agent engineering intuition (memory, retrieval, storage trade-offs) | Q1 |
-| Arabic NLP depth (data, diacritization, evaluation, fine-tuning) | Q2 |
+| Arabic NLP depth (model + dataset selection) | Q2 |
-| Shipping — can you actually deploy something live | Q3 + Q4 |
+| Shipping — deploy something live | Q3 + Q4 |
+| Agent building with real tooling (LangChain) | Q5 |
 
 ## The stack you will touch
 
@@ -34,19 +35,20 @@ You are interviewing to join the team that builds **agents like Cumin** — the
 | **Qabilah (قبيلة)** | Arabic tech social / community platform | https://qabilah.com |
 | **Mortakaz (مُرتكز)** | Directory of ~686 Arab-built products | https://mortakaz.com |
 | **Ghaymah (غيمة)** | Arabic cloud platform (PaaS) | https://ghaymah.systems |
-| **Ghaymah Dashboard** | Where you sign up and deploy | https://deploy.ghaymah.systems |
+| **Ghaymah Dashboard** | Where you sign up, get AI models, and deploy | https://deploy.ghaymah.systems |
 
 ## Time budget (60 min total)
 
 | Task | Folder | Budget |
 |---|---|---|
 | Read this README + set up | — | 5 min |
-| Qabilah profile + ecosystem note | `common-qabilah/` | 8 min |
+| Qabilah profile + check-in | `common-qabilah/` | 3 min |
 | Mortakaz discovery + integration proposal | `common-mortakaz/` | 10 min |
 | Q1 — Cumin memory module design | `q1-cumin-memory/` | 15 min |
-| Q2 — Arabic TTS or STT fine-tune plan | `q2-arabic-tts-stt/` | 15 min |
+| Q2 — Arabic TTS/STT model + dataset proposal | `q2-arabic-tts-stt/` | 6 min |
-| Q3 — Ghaymah signup | `q3-ghaymah-signup/` | 5 min |
+| Q3 — Ghaymah signup | `q3-ghaymah-signup/` | 4 min |
-| Q4 — Deploy a static site on Ghaymah | `q4-static-site-deploy/` | 12 min |
+| Q4 — Deploy a static site on Ghaymah | `q4-static-site-deploy/` | 8 min |
+| Q5 — LangChain agent on Ghaymah's GenAI services | `q5-llm-agent/` | 9 min |
 | **Total** | | **≈ 60 min** |
 
 > ⏱️ Be honest about your time. A focused, complete 60-minute submission beats a half-finished 2-hour one. We look at commit timestamps.
@@ -56,7 +58,7 @@ You are interviewing to join the team that builds **agents like Cumin** — the
 1. Work **inside this repo**. Each question has its own folder with a task description and an answer template. Fill in your answers **in place**.
 2. Do not rename or move the question folders.
 3. Never commit real credentials, tokens, or passwords — use placeholders like `<REDACTED>`.
-4. For Q4, commit your actual site source under `q4-static-site-deploy/site/`.
+4. For Q4, commit your actual site source under `q4-static-site-deploy/site/`; for Q5 under `q5-llm-agent/`.
 5. You may use any public resources (docs, model cards, papers, blogs) — cite them inline.
 
 ## Repository structure
@@ -71,14 +73,18 @@ ghaymah-genai-exam/
 ├── q1-cumin-memory/
 │   └── cumin-memory-module.md     ← task + answer template
 ├── q2-arabic-tts-stt/
-│   └── arabic-tts-stt-finetune.md ← task + answer template
+│   └── arabic-tts-stt-proposal.md ← task + answer template
 ├── q3-ghaymah-signup/
 │   └── ghaymah-signup.md          ← task + answer template
-└── q4-static-site-deploy/
+├── q4-static-site-deploy/
-    ├── static-site-deploy.md      ← task + answer template
+│   ├── static-site-deploy.md      ← task + answer template
-    └── site/                      ← put your site files here
+│   └── site/
-        ├── index.html
+│       ├── index.html
-        └── style.css
+│       └── style.css
+└── q5-llm-agent/
+    ├── llm-agent.md               ← task + answer template
+    ├── agent.py                   ← starter LangChain agent
+    └── requirements.txt
 ```
 
 ## How to submit (GitPasha)
@@ -89,18 +95,19 @@ ghaymah-genai-exam/
    git add . && git commit -m "q1: memory module design"
    ```
 3. `git push origin main` when done.
-4. Verify on GitPasha that every file (including your Q4 site source) is present.
+4. Verify on GitPasha that every file (including your Q4 site source and Q5 code) is present.
 
 ## Scoring rubric
 
 | Question | Weight | What “excellent” looks like |
 |---|---|---|
-| common-qabilah | 10% | Real profile URL + a note showing genuine exploration, not copy-paste |
+| common-qabilah | 5% | Real profile URL |
 | common-mortakaz | 15% | Two concrete products, technically-grounded integration with Ghaymah's AI stack, honest challenges |
-| Q1 memory module | 30% | Clear memory taxonomy, concrete storage choices, sensible write/read policy, runnable pseudocode, Ghaymah integration |
+| Q1 memory module | 25% | Clear memory taxonomy, concrete storage choices, sensible write/read policy, runnable pseudocode, Ghaymah integration |
-| Q2 TTS/STT | 25% | Correct Arabic data/preprocessing/eval, realistic training config, deployable plan |
+| Q2 TTS/STT | 15% | A well-justified model + dataset with correct Arabic specifics (dialect, diacritization, license) |
 | Q3 signup | 5% | Confirmed signup + thoughtful platform observations |
 | Q4 static site | 15% | A live URL that resolves + source committed + a short write-up |
+| Q5 LangChain agent | 20% | A working agent wired to Ghaymah's LLM endpoint, with at least one tool and clear code |
 
 ---
 

common-qabilah/qabilah-ecosystem.md

@@ -1,20 +1,14 @@
-# Qabilah (قبيلة) — Ecosystem Introduction
+# Qabilah (قبيلة) — Profile & Ecosystem Check-in
 
-⏱ **Budget: ~8 minutes** · Weight: 10%
+⏱ **Budget: ~3 minutes** · Weight: 5%
 
 ## The task
 
-[Qabilah](https://qabilah.com) is an Arabic tech social & community platform — think of it as the Arabic-speaking tech community's home. Before you design agents for this ecosystem, you should know who lives in it.
+[Qabilah](https://qabilah.com) is an Arabic tech social & community platform — think of it as the Arabic-speaking tech community's home. Before you build agents for this ecosystem, you should know who lives in it.
 
 1. Go to https://qabilah.com and **create a profile** (if you don't already have one). Use a real name and a one-line bio about what you build.
-2. Browse the feed / communities. Find **three Arabic AI or GenAI projects, people, or companies** that interest you.
+2. Record your profile URL below.
-3. Write a short note (150–250 words) answering: **what is Qabilah, and what role does it play in the Arabic tech ecosystem?**
+3. (Optional, one line) In your own words: what is Qabilah?
-
-## What to submit
-
-Fill in the template below, in this file. Put your profile URL in section 1 and your note in section 2.
-
----
 
 ## ANSWER — Qabilah
 
@@ -24,16 +18,6 @@ Fill in the template below, in this file. Put your profile URL in section 1 and
 https://qabilah.com/profile/<your-handle>/posts
 ```
 
-### 2. Ecosystem note (150–250 words)
+### 2. One line: what is Qabilah?
 
-> _Write here. What is Qabilah? What problem does it solve for Arabic-speaking builders? How does it connect people/projects/funding? You may write in Arabic or English._
+> _optional — one sentence_ 
-
-<!-- replace with your note -->
-
-### 3. Three Arabic AI projects / people I found
-
-| # | Name | What it does | Why it interested me |
-|---|---|---|---|
-| 1 | | | |
-| 2 | | | |
-| 3 | | | |

q2-arabic-tts-stt/arabic-tts-stt-finetune.md

@@ -1,57 +0,0 @@
-# Q2 — Fine-tuning an Arabic TTS or STT
-
-⏱ **Budget: ~15 minutes** · Weight: 25%
-
-## Choose ONE option
-
-- **Option A — TTS.** Fine-tune an open Arabic (or multilingual) text-to-speech model — e.g. Coqui **XTTS-v2**, **VITS**, or **StyleTTS2** — on a single-speaker Arabic dataset.
-- **Option B — STT.** Fine-tune **Whisper** (e.g. `whisper-small`, `large-v3`) on Arabic speech — e.g. Mozilla **Common Voice `ar`**, **MGB-2**, or a custom corpus.
-
-## Produce a runnable guide covering
-
-1. **Model & dataset choice** — justify it; cite dataset sizes, license, and dialect (MSA vs. Egyptian vs. Gulf vs. Maghrebi).
-2. **Data preprocessing** — audio resampling/normalization, text normalization, and the Arabic-specific gotchas: **diacritization (تشكيل)**, letter variants (أ/إ/آ, ة/ه, ى/ي), and (for STT) whether to strip diacritics before computing WER. Train/val split.
-3. **Training setup** — framework (e.g. Hugging Face Trainer, Coqui TTS, NeMo), **LoRA vs. full fine-tune**, key hyperparameters (batch size, LR, epochs, warmup), hardware, and a rough time/cost estimate.
-4. **Evaluation** — for STT: **WER/CER** (and how to compute them fairly for Arabic); for TTS: **MOS**, **speaker similarity (SECS)**, and using an ASR to measure intelligibility. Include the actual metric definitions/commands.
-5. **Deployment on Ghaymah** — GPU sizing, container vs. function, serving stack, latency, and how the model is served behind an API.
-6. **Risks & mitigations** — dialect coverage, hallucination, diacritic fidelity, MSA vs. dialect mismatch, data licensing.
-
-Include **real code snippets** (Python / Hugging Face / CLI). Cite sources inline.
-
-## Deliverable
-
-Fill in the template below. State clearly which option you chose.
-
----
-
-## ANSWER — Arabic TTS/STT Fine-tune
-
-**Option chosen:** A / B  (delete one)
-
-### 1. Model & dataset choice
-
-> _write here_ 
-
-### 2. Data preprocessing
-
-> _write here + code snippets_ 
-
-### 3. Training setup
-
-> _write here + code/config snippets_ 
-
-### 4. Evaluation
-
-> _write here + metric definitions/commands_ 
-
-### 5. Deployment on Ghaymah
-
-> _write here_ 
-
-### 6. Risks & mitigations
-
-| Risk | Mitigation |
-|---|---|
-| | |
-| | |
-| | |

q2-arabic-tts-stt/arabic-tts-stt-proposal.md

@@ -0,0 +1,39 @@
+# Q2 — Propose an Arabic TTS or STT Model + Dataset
+
+⏱ **Budget: ~6 minutes** · Weight: 15%
+
+## Choose ONE option
+
+- **Option A — TTS.** Propose a text-to-speech model to fine-tune for Arabic.
+- **Option B — STT.** Propose a speech-to-text model to fine-tune for Arabic.
+
+## The task
+
+Propose **one model** and **one dataset**, with a short justification. No training, no running code — just a well-reasoned pick. (Short code/CLI snippets are allowed but not required.)
+
+Cover:
+
+1. **Model** — name it, and say why: architecture, license, multilingual/Arabic support.
+2. **Dataset** — name it, and say why: size, dialect (MSA vs. Egyptian vs. Gulf vs. Maghrebi), license, where to get it.
+3. **Why this pairing works for Arabic** — 1–2 sentences (e.g. diacritization handling, dialect coverage).
+4. **One key risk** — 1 sentence.
+
+## ANSWER — Arabic TTS/STT Proposal
+
+**Option chosen:** A / B  (delete one)
+
+### Proposed model
+
+> _write here_ 
+
+### Proposed dataset
+
+> _write here_ 
+
+### Why this pairing works for Arabic
+
+> _write here_ 
+
+### One key risk
+
+> _write here_ 

q5-llm-agent/agent.py

@@ -0,0 +1,47 @@
+"""
+Q5 starter — a minimal LangChain agent on Ghaymah's GenAI services.
+
+1. Get base_url + API key + model ID from https://deploy.ghaymah.systems
+2. pip install -r requirements.txt
+3. python agent.py "what is 12 * 7 plus 4?"
+"""
+import os
+import sys
+
+from langchain_openai import ChatOpenAI
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain.tools import tool
+from langchain_core.prompts import ChatPromptTemplate
+
+# --- Ghaymah GenAI config (fill these in / use env vars) ---
+BASE_URL = os.getenv("GHAYMAH_BASE_URL", "https://<ghaymah-llm-endpoint>/v1")
+API_KEY = os.getenv("GHAYMAH_API_KEY", "<redacted>")
+MODEL = os.getenv("GHAYMAH_MODEL", "<model-id-from-dashboard>")
+
+llm = ChatOpenAI(base_url=BASE_URL, api_key=API_KEY, model=MODEL, temperature=0)
+
+
+@tool
+def calculator(expression: str) -> str:
+    """Evaluate a simple arithmetic expression and return the result."""
+    try:
+        return str(eval(expression, {"__builtins__": {}}, {}))
+    except Exception as e:  # noqa: BLE001
+        return f"error: {e}"
+
+
+tools = [calculator]
+prompt = ChatPromptTemplate.from_messages(
+    [
+        ("system", "You are a helpful Arabic/English assistant. Use the calculator tool when you need arithmetic."),
+        ("human", "{input}"),
+        ("placeholder", "{agent_scratchpad}"),
+    ]
+)
+
+agent = create_tool_calling_agent(llm, tools, prompt)
+executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+if __name__ == "__main__":
+    q = sys.argv[1] if len(sys.argv) > 1 else "ما حاصل 12 × 7 + 4؟"
+    print(executor.invoke({"input": q})["output"])

q5-llm-agent/llm-agent.md

@@ -0,0 +1,50 @@
+# Q5 — Build a simple LLM agent with LangChain (on Ghaymah's GenAI services)
+
+⏱ **Budget: ~9 minutes** · Weight: 20%
+
+## The task
+
+Build a small **LLM agent** using **LangChain**, and point it at **Ghaymah's GenAI services** (the ready-to-use LLM models you saw in the dashboard).
+
+Requirements:
+
+1. Use LangChain (Python) with an **OpenAI-compatible** client pointed at Ghaymah's inference endpoint. Get the **base URL**, **API key**, and a **model ID** from https://deploy.ghaymah.systems (see the AI / models section).
+2. Give the agent **at least one tool** — e.g. a calculator, a "save note" memory tool, or a tiny retrieval tool.
+3. (Optional, +bonus) Wire it to the static site from **Q4** — the page calls your agent's endpoint and shows the reply.
+
+There's a starter `agent.py` + `requirements.txt` in this folder you may extend or replace.
+
+## Deliverable
+
+Fill in the template below and commit your code in this folder.
+
+---
+
+## ANSWER — LangChain agent
+
+### 1. What my agent does
+
+> _one or two lines_ 
+
+### 2. Architecture (LangChain components)
+
+| Component | What I used |
+|---|---|
+| Model (LLM) | |
+| Tool(s) | |
+| Prompt | |
+| Executor | |
+
+### 3. How it uses Ghaymah's GenAI services
+
+> _base URL pattern, model ID, how you got the key (do not paste the key)_ 
+
+### 4. Code
+
+> _commit your code in this folder (agent.py etc.) and reference it here_ 
+
+### 5. How to run / deploy it
+
+```bash
+# commands
+```

q5-llm-agent/requirements.txt

@@ -0,0 +1,2 @@
+langchain
+langchain-openai