diff --git a/README.md b/README.md index cb8dee5..737f308 100644 --- a/README.md +++ b/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. -4. Sign up to **Ghaymah** and **deploy a simple static website**. +3. Propose an **Arabic TTS or STT** model + dataset. +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 | -| Shipping — can you actually deploy something live | Q3 + Q4 | +| Arabic NLP depth (model + dataset selection) | Q2 | +| 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 | -| Q3 — Ghaymah signup | `q3-ghaymah-signup/` | 5 min | -| Q4 — Deploy a static site on Ghaymah | `q4-static-site-deploy/` | 12 min | +| Q2 — Arabic TTS/STT model + dataset proposal | `q2-arabic-tts-stt/` | 6 min | +| Q3 — Ghaymah signup | `q3-ghaymah-signup/` | 4 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 ``. -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/ - ├── static-site-deploy.md ← task + answer template - └── site/ ← put your site files here - ├── index.html - └── style.css +├── q4-static-site-deploy/ +│ ├── static-site-deploy.md ← task + answer template +│ └── site/ +│ ├── index.html +│ └── 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 | -| Q2 TTS/STT | 25% | Correct Arabic data/preprocessing/eval, realistic training config, deployable plan | +| Q1 memory module | 25% | Clear memory taxonomy, concrete storage choices, sensible write/read policy, runnable pseudocode, Ghaymah integration | +| 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 | --- diff --git a/common-qabilah/qabilah-ecosystem.md b/common-qabilah/qabilah-ecosystem.md index a5221c9..ed43e1b 100644 --- a/common-qabilah/qabilah-ecosystem.md +++ b/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. -3. Write a short note (150–250 words) answering: **what is Qabilah, and what role does it play in the Arabic tech ecosystem?** - -## What to submit - -Fill in the template below, in this file. Put your profile URL in section 1 and your note in section 2. - ---- +2. Record your profile URL below. +3. (Optional, one line) In your own words: what is Qabilah? ## 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//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._ - - - -### 3. Three Arabic AI projects / people I found - -| # | Name | What it does | Why it interested me | -|---|---|---|---| -| 1 | | | | -| 2 | | | | -| 3 | | | | +> _optional — one sentence_ diff --git a/q2-arabic-tts-stt/arabic-tts-stt-finetune.md b/q2-arabic-tts-stt/arabic-tts-stt-finetune.md deleted file mode 100644 index 3bac998..0000000 --- a/q2-arabic-tts-stt/arabic-tts-stt-finetune.md +++ /dev/null @@ -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 | -|---|---| -| | | -| | | -| | | diff --git a/q2-arabic-tts-stt/arabic-tts-stt-proposal.md b/q2-arabic-tts-stt/arabic-tts-stt-proposal.md new file mode 100644 index 0000000..cb60bc1 --- /dev/null +++ b/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_ diff --git a/q5-llm-agent/agent.py b/q5-llm-agent/agent.py new file mode 100644 index 0000000..40c56c4 --- /dev/null +++ b/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:///v1") +API_KEY = os.getenv("GHAYMAH_API_KEY", "") +MODEL = os.getenv("GHAYMAH_MODEL", "") + +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"]) diff --git a/q5-llm-agent/llm-agent.md b/q5-llm-agent/llm-agent.md new file mode 100644 index 0000000..e74f31e --- /dev/null +++ b/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 +``` diff --git a/q5-llm-agent/requirements.txt b/q5-llm-agent/requirements.txt new file mode 100644 index 0000000..8334736 --- /dev/null +++ b/q5-llm-agent/requirements.txt @@ -0,0 +1,2 @@ +langchain +langchain-openai