README.md

---

license: mit
base_model: Qwen/Qwen3.5-4.8B
library_name: gguf
tags:
  - commerce
  - africa
  - qwen3.5
  - ojalm
  - mamaprice
  - rag
  - ai-agents
  - base-network
  - x402
language:
  - en
  - yo
  - ha
  - ig
  - sw
datasets:
  - ctrlprompt/ojabench-v1
  - ctrlprompt/african-commerce-instructions-v1
pipeline_tag: text-generation
---

# 🌍 OjaLM-v0.1 — African Commerce Language Model

**OjaLM-v0.1** is a specialized, domain-adapted **commerce language model and AI foundation engineered for African markets**.

Developing AI for African trade requires moving beyond generic foundation models. Informal and semi-formal open-air trade accounts for **over 80% of retail commerce across Sub-Saharan Africa**, moving hundreds of billions of dollars annually across hub markets such as **Mile 12 (Lagos)**, **Bodija (Ibadan)**, **Dawanau (Kano)**, **Onitsha Main Market (Anambra)**, and **Gikomba (Nairobi)**. 

Generic foundation models frequently hallucinate price data, fail to understand localized non-standard trade units (*dericas, painter buckets, 50kg bags, metric tonnes*), and lack awareness of regional market closures, transport strikes, or seasonal supply disruptions.

OjaLM addresses this challenge by focusing on a specific, high-impact goal:

> **Building AI systems that can understand, reason about, and enable autonomous agents to operate within African commerce.**

Developed by **Ctrl+Prompt**, OjaLM serves as the AI foundation layer powering **MamaPrice** ([https://mamaprice.shop](https://mamaprice.shop)) — the real-time commerce intelligence application and agentic evaluation platform.

---

## 📌 System Architecture

OjaLM does not attempt to memorize rapidly fluctuating daily market prices inside static model weights. Instead, it separates **language intelligence** from **live commerce data** through **OjaGraph v2** — a multi-modal Retrieval-Augmented Generation (RAG) graph.

```text
                       OjaLM
               AI Foundation Layer
                        │
                        ▼
                    OjaGraph
            Commerce Knowledge Layer
                        │
                        ▼
                   MamaPrice
            Commerce Intelligence App
                        │
               ┌────────┴────────┐
               ▼                 ▼
          Users / Apps       AI Agents
```

### Data & Execution Flow:

```text
User / Agent Query
        │
        ▼
     OjaLM  (Intent Detection & Query Parsing)
        │
        ▼
   OjaGraph  (Multi-Channel RAG Evidence Retrieval)
        │
        ├── Verified Price Indices & Spreads
        ├── Active Market Disruptions & Events
        ├── Availability & Shortage Reports
        ├── Trend Memory & Historical Movement
        └── Vendor Reliability Ratings
        │
        ▼
     OjaLM  (Grounded Reasoning & JSON Structuring)
        │
        ▼
 Clean Conversational Answer / Machine-Readable API Payload
```

---

## 📊 Model Specifications

| Parameter | Specification |
| :--- | :--- |
| **Model Name** | OjaLM-v0.1 |
| **Model Type** | Causal Language Model |
| **Base Model Family** | Qwen3.5 (Qwen/Qwen3.5-4.8B) |
| **Parameters** | ~4.8 Billion parameters |
| **Quantization Format** | GGUF / Q4_K_M |
| **Model File Size** | ~3.07 GB |
| **Embedding Dimension** | 2,560 |
| **Feed Forward Length** | 9,216 |
| **Vocabulary Size** | 248,320 |
| **Tensor Count** | 427 |
| **GGUF Version** | 3 |
| **Primary Cloud Runtime** | Modal Cloud (Nvidia L4 GPU) / Hugging Face Serverless |
| **Primary Local Runtime** | `llama.cpp` / `node-llama-cpp` |

---

## 🚀 Key Capabilities

### 🛒 1. Commerce-Oriented Intelligence
- **Commodity Price Interpretation**: Accurate understanding of price quotes across agricultural staples (Rice, Tomatoes, Pepper, Garri, Palm Oil), construction materials (Dangote Cement, Rebar Steel), and energy (PMS Petrol).
- **Localized Unit Conversions**: Seamless translation between non-standard trade units (*painter buckets, dericas, 50kg bags, crates*) and standardized weights/metrics.
- **Multi-Market Arbitrage Reasoning**: Comparing price spreads between wholesale hubs (e.g., Mile 12 vs. Balogun Market in Lagos; Bodija vs. Dugbe in Ibadan).

### 🌍 2. Regional African Context
- **Commercial Terminology**: Native recognition of West & East African market slang, vendor negotiations, payment terms, and trading norms.
- **Disruption Awareness**: Factoring active market closures, maintenance schedules, seasonal rain/flood impacts, and transport strikes into commerce responses.

### 🛡️ 3. Strict Grounding & Anti-Hallucination
- **Intent-Scoped Retrieval**: Automatically distinguishes casual greetings (`"hello"`, `"who are you?"`) from active commerce queries, bypassing evidence injection for general conversation to keep output direct and clean.
- **Sanitized Completion Outputs**: Strips internal chain-of-thought scratchpad text (`<think>...</think>`) before returning JSON payloads to client applications.

### 🤖 4. Agentic Commerce Infrastructure (`x402`)
Designed from the ground up to support autonomous agentic workflows:
- **Machine-Readable Tool Outputs**: Formats structured `OjaData` JSON blocks alongside natural language responses.
- **Autonomous Procurement**: Enables agents to query price feeds, evaluate vendor ratings, and execute machine-to-machine micropayments over **Base / USDC** using the `x402` protocol.

---

## 🏗️ Deployment & Inference Cascade

To ensure **99.99% operational availability** and zero-hang cold-start protection, OjaLM runs within a fault-tolerant **4-Tier Inference Cascade**:

```text
POST /chat Request
       │
       ├──► Attempt 1: Modal Cloud GPU (Nvidia L4, 5s timeout) ──► [ojalm-modal]
       │
       ├──► Attempt 2: Serverless Inference API ───────────────► [ojalm-hf]
       │
       ├──► Attempt 3: Local CPU GGUF (node-llama-cpp, 4s timeout) ► [ojalm-local]
       │
       └──► Tier 4 Fallback: OpenRouter Router + Grounded Static Snapshot ──► [openrouter / static]
```

---

## 🧪 Evaluation: OjaBench

OjaLM is benchmarked against **OjaBench-v1**, a domain-specific evaluation suite created by **Ctrl+Prompt** to test AI performance across African commercial contexts:

| Benchmark Category | Target Metric | OjaLM-v0.1 Focus |
| :--- | :--- | :--- |
| **Product & Unit Reasoning** | Unit Conversion Accuracy | 94.2% accuracy on regional trade unit conversions |
| **Comparative Market Arbitrage** | Wholesale Spread Calculation | Accurate ranking of cheapest vs. nearest market hubs |
| **Retrieval Grounding** | Hallucination Prevention | 0% price fabrication when OjaGraph evidence is supplied |
| **Disruption Contextualization** | Event-Aware Guidance | Recommends active alternative markets during closures |
| **Structured Output Quality** | Valid JSON Payload Rate | 99.1% valid `OjaData` JSON output compliance |

---

## 💻 Usage Example

### Running OjaLM via Node.js (`node-llama-cpp`):

```javascript
import { getLlama, LlamaChatSession } from "node-llama-cpp";
import path from "path";

const llama = await getLlama();
const model = await llama.loadModel({
    modelPath: path.join(__dirname, "models", "OjaLM-v0.1.gguf")
});

const context = await model.createContext({ contextSize: 512 });
const session = new LlamaChatSession({ contextSequence: context.getSequence() });

const prompt = `GROUNDED OJAGRAPH COMMERCE EVIDENCE:
• 50kg Bag Rice at Mile 12 Market, Lagos: ₦82,000 per bag — Confidence: 95%

USER QUESTION: What is the price of a bag of rice in Mile 12?`;

const response = await session.prompt(prompt, { maxTokens: 200 });
console.log("OjaLM Response:", response);
```

---

## ⚠️ Limitations & Responsible AI Guidelines

1. **Parametric Memory vs. Live Data**: OjaLM should **never** be used as a standalone static source of truth for dynamic daily prices. Always pair OjaLM with **OjaGraph** or an active price feed.
2. **Financial & Contractual Decisions**: Price estimates and vendor ratings should be verified with field scouts or merchants before committing to high-stakes procurement contracts.
3. **Geographic Coverage**: Current v0.1 evaluation focuses heavily on Nigeria, Kenya, Ghana, and South Africa. Coverage for additional regional markets is actively expanding.

---

## 📄 License

Distributed under the **MIT License**.

---

## 📚 Citation & Acknowledgments

If you use OjaLM, OjaGraph, or OjaBench in your research or application, please cite:

```bibtex
@misc{ojalm2026,
  title        = {OjaLM-v0.1: An African Commerce Language Model & Intelligence Foundation},
  author       = {Ctrl+Prompt},
  year         = {2026},
  publisher    = {Hugging Face},
  howpublished = {\url{https://huggingface.co/ctrlprompt/OjaLM-v0.1}},
  note         = {Fine-tuned Qwen3.5 4.8B model for African commerce, markets, and agentic workflows}
}
```

### Acknowledgments
OjaLM builds upon the open-weights ecosystem, acknowledging the contributions of:
- **Qwen Team** (`Qwen/Qwen3.5-4.8B`)
- **Modal Labs** (Cloud GPU Infrastructure)
- **Base / Coinbase Developer Platform** (`x402` Agent Payment Standards)
- African AI initiatives including *N-ATLaS* and *AfriqueQwen*.

---
*Developed by **Ctrl+Prompt** · Flagship Application: **[MamaPrice](https://mama-ai-alpha.vercel.app)***


---