README_math.md

metadata

language:
  - yo
  - en
pipeline_tag: text-generation
library_name: transformers
tags:
  - yoruba
  - english
  - mathematics
  - arithmetic
  - reasoning
  - education
  - low-resource
  - african-languages
  - cohere2

Yorùbá Math Reasoner

Built by Adediran Adeyemi

A language model that solves arithmetic and word problems step by step, in Yorùbá or English. Ask the way you would say it: in English, in Yorùbá, with or without tone marks, or a mix of both. The model shows its working, checks its own answer, and corrects itself when the check fails.

It accompanies the research paper Bridging the Math Reasoning Gap for African Languages: Fine-Tuning and Quantization of LLMs on Pedagogical Yoruba Arithmetic Data.

If you use this model, build on it, or write about it, please credit Adediran Adeyemi and link back to this repository. You are welcome to connect with me on LinkedIn: https://www.linkedin.com/in/adediran-adeyemi

---

What the model can do

• Solve arithmetic step by step. Addition, subtraction, multiplication, division (with remainders), fractions, decimals, percentages, ratios and simple equations.
• Solve short word problems at primary and JSS level, such as shopping, money in naira, time conversion and sharing.
• Work in Yorùbá and English. It answers in the language of the question. Yorùbá can be fully marked, unmarked, partly marked, or mixed into English. The model restores the missing marks itself before reasoning.
• Read and write Yorùbá number words. Numbers are written thousand-first, so 34,250 is ẹgbẹrun mẹ́rinlélọgbọ̀n ó lé igba ó lé àádọ́ta.
• Check its own work. It verifies a result by a second route (the reverse operation, re-reading the number word, or another method). If the check disagrees, it goes back through the steps, names the first step that fails, corrects it, and checks again.
• Review a student's answer. Give it a question with a student's working. It solves the problem first, then says which step, if any, is wrong.
• Say when it is unsure instead of guessing.

---

Examples

Each example shows what you type and the kind of answer the model is built to give.

Addition

You type: Work out 9947 + 9128. Model:

9947 + 9128
Add the ones, tens, hundreds and thousands, carrying when needed.
7 + 8 = 15, write 5, carry 1
4 + 2 + 1 = 7
9 + 1 = 10, write 0, carry 1
9 + 9 + 1 = 19
Final answer: 9947 + 9128 = 19075

Multiplication

You type: Calculate 451 x 29 step by step. Model: splits 29 into 20 and 9, finds 451 × 20 = 9020 and 451 × 9 = 4059, then adds them. Final answer: 13079

Division with a remainder

You type: Divide 429 by 10. What is the remainder? Final answer: 42 remainder 9

Fractions

You type: Find the sum of 3/6 and 1/3. Model: simplifies 3/6 to 1/2, finds a common denominator of 6, and adds 3/6 + 2/6. Final answer: 5/6

Word problem

You type: Amina buys 16 loaves of bread at ₦320 each. How much does Amina pay? Model: multiplies 16 × 320. Final answer: ₦5,120

Ratio

You type: Simplify the ratio 27:18. Model: finds the greatest common factor of 27 and 18 (9) and divides both sides by it. Final answer: 3:2

Asking in Yorùbá

You type: Èló ni 7849 + 9642? Model: shows the working in Yorùbá, then ends with the answer line. Ìdáhùn Ìkẹyìn: 17491

You type: Ṣírò 449 ÷ 5, kí o sì fi ìyókù hàn. Ìdáhùn Ìkẹyìn: 89, ìyókù 4

You type: Yí wákàtí 39 padà sí ìṣẹ́jú. Ìdáhùn Ìkẹyìn: 2340 ìṣẹ́jú

The model checks itself and fixes a mistake

This is the behaviour that sets the model apart. Here is the shape of a self-correction on 47 + 28:

Step 1: 40 + 20 = 60
Step 2: 7 + 8 = 16
Step 3: 60 + 16 = 76
I get 76 as my answer.

Let me check it before I settle.
Reverse check: 76 - 28 = 48, yet the original value was 47. They disagree, so something is wrong.
  Step 1: 40 + 20 = 60 ✓
  Step 2: 7 + 8 = 15 (✗ 16)
Step 2 is wrong: I wrote 16 but the calculation gives 15.
Corrected answer: 75.
Re-check by reversing the last step: 75 - 28 = 47. It matches now.

Final answer: 47 + 28 = 75

The examples show the style of answer the model is designed to give. The numeric answers are correct, but the exact wording of the working can differ from run to run. Please check important results yourself.

---

How to use it

The model is a chat model. Send the question exactly as the user typed it, with the system prompt below. Reasoning mode must be on.

import re, torch
from transformers import AutoModelForCausalLM, AutoTokenizer

repo = "adeyemi001/Yor_math"

tok = AutoTokenizer.from_pretrained(repo)
model = AutoModelForCausalLM.from_pretrained(repo, dtype=torch.bfloat16, device_map="auto")

SYSTEM = (
    "You are Aya, a careful maths tutor who works in Yoruba and English. "
    "Answer in the language of the question and show each step. "
    "Yoruba may be written with full tone marks, with none, with some, or mixed into English: "
    "read it all, restore the marks yourself before reasoning when they are missing, "
    "and write your own Yoruba with correct marks. "
    "Write Yoruba number words thousand-first: ẹgbẹrun + the number of thousands, then \"ó lé\" + the rest "
    "(34250 = ẹgbẹrun mẹ́rinlélọgbọ̀n ó lé igba ó lé àádọ́ta). "
    "A comma inside a number such as 10,000 is a thousands separator, not a decimal point; "
    "a point (.) is the decimal point. "
    "Never trust a result until it is checked by an independent route "
    "(reverse operation, re-reading the number word, or a second method). "
    "If the check disagrees, re-walk the steps one by one, name the FIRST step that fails, "
    "correct it, recompute the steps after it, and check again. "
    "When a student's answer or working is given, solve it yourself first, "
    "then say which step (if any) is wrong. "
    "If you cannot be sure, say so instead of guessing."
)

messages = [
    {"role": "system", "content": SYSTEM},
    {"role": "user", "content": "Amina buys 16 loaves of bread at ₦320 each. How much does Amina pay?"},
]

text = tok.apply_chat_template(messages, tokenize=False, add_generation_prompt=True, enable_thinking=True)
inputs = tok(text, return_tensors="pt", add_special_tokens=False).to(model.device)

out = model.generate(**inputs, max_new_tokens=1800, do_sample=False)
raw = tok.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=False)

# The model reasons first, then gives a short final response.
working = raw.split("<|END_THINKING|>")[0].replace("<|START_THINKING|>", "").strip()
answer = raw.split("<|START_RESPONSE|>")[-1].split("<|END_RESPONSE|>")[0].strip()
print(working)
print("ANSWER:", answer)

Tips

• Use greedy decoding (do_sample=False).
• Allow up to about 1800 new tokens. Checking and correcting makes the working longer than a plain answer.
• To stop early, you can end generation at the line that starts with Final answer: (or Ìdáhùn Ìkẹyìn: in Yorùbá).
• Send the question as typed. Do not add extra instructions to it.
• The model needs about 10 GB of free memory in bfloat16. A GPU is much faster than a CPU.
• Do not use int8 quantisation on CPU with this model. It corrupts the output. Use bfloat16.

---

Limitations

• The model works best on arithmetic, fractions, decimals, percentages, simple equations and short word problems at primary and JSS level. It is not built for algebra, geometry proofs, calculus or advanced mathematics.
• Like any language model, it can write a confident answer that is wrong, even with self-checking. Always check the result, especially for long calculations.
• Very large numbers and long multi-step word problems are less reliable.
• Yorùbá number words and mathematical terms follow one consistent convention. Other regional conventions are not fully covered.
• It is a learning aid. Do not use it as the only source for financial, legal or high-stakes calculations.

---

Citation and credit

If you use this model in research, teaching or products, please cite it and credit the author:

@misc{adeyemi_yoruba_math_reasoner,
  author = {Adeyemi, Adediran},
  title  = {Bridging the Math Reasoning Gap for African Languages: Fine-Tuning and Quantization of LLMs on Pedagogical Yoruba Arithmetic Data},
  year   = {2026},
  publisher = {Hugging Face},
  url    = {https://huggingface.co/adeyemi001/Yor_math}
}

About the author

Adediran Adeyemi is a data scientist, machine learning engineer and geospatial analyst based in Lagos, Nigeria, working on Yorùbá language AI.

Questions, feedback, collaboration or research partnerships are welcome. Connect with me on LinkedIn: https://www.linkedin.com/in/adediran-adeyemi