chafikboulealam/smart-travel-gemma2-darija

Smart Travel Assistant - Gemma-2-2b-it Fine-tuned (Darija & French)

Fully merged float16 model ready for direct inference — no adapter loading required.

A QLoRA fine-tuned and fully merged version of google/gemma-2-2b-it for a Smart Travel Assistant application. The model accepts travel queries in French or Moroccan Darija and generates structured JSON itineraries matching the application frontend schema.

---

Model Details

Property	Value
Base Model	google/gemma-2-2b-it
Architecture	Gemma2ForCausalLM
Fine-tuning Method	QLoRA (LoRA rank=16, alpha=32, dropout=0.05)
Training Framework	TRL SFTTrainer + PEFT
Merge Status	Fully merged (LoRA adapter merged into base weights)
Precision	float16
Model Size	3B parameters
Languages	French (fr), Moroccan Darija (ar)
License	Apache 2.0

---

Task Description

The model receives a travel query (in French or Darija) and returns a strict JSON object matching the frontend itinerary schema. The output is designed for direct parsing with JSON.parse() on the client side.

Output JSON Schema

{
  "days": [
    {
      "date": "YYYY-MM-DD",
      "activities": [
        {
          "id": "act-1",
          "time": "09:00",
          "title": "Activity name",
          "location": "Location, City",
          "description": "Brief description of the activity.",
          "durationMinutes": 120
        }
      ]
    }
  ]
}

---

Usage

Direct Inference with transformers

from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline
import torch
import json

model_id = "chafikboulealam/smart-travel-gemma2-darija"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.float16,
    device_map="auto"
)

def generate_itinerary(query: str) -> dict:
    messages = [{"role": "user", "content": query}]
    prompt = tokenizer.apply_chat_template(
        messages, tokenize=False, add_generation_prompt=True
    )
    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    with torch.no_grad():
        outputs = model.generate(
            **inputs,
            max_new_tokens=512,
            temperature=0.1,
            do_sample=True,
            pad_token_id=tokenizer.eos_token_id
        )
    response = tokenizer.decode(
        outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True
    )
    return json.loads(response)

# French query
result = generate_itinerary("Planifie-moi 3 jours a Fes avec les monuments historiques.")
print(json.dumps(result, indent=2, ensure_ascii=False))

# Darija query  
result = generate_itinerary("Khettit liya voyage l Marrakech juj iyyam.")
print(json.dumps(result, indent=2, ensure_ascii=False))

Using HuggingFace Inference API (REST)

curl -X POST \
  https://api-inference.huggingface.co/models/chafikboulealam/smart-travel-gemma2-darija \
  -H "Authorization: Bearer YOUR_HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": "<start_of_turn>user\nPlanifie-moi 2 jours a Marrakech.<end_of_turn>\n<start_of_turn>model\n",
    "parameters": {
      "max_new_tokens": 512,
      "temperature": 0.1,
      "do_sample": true,
      "return_full_text": false
    }
  }'

Postman Configuration

Method:  POST
URL:     https://api-inference.huggingface.co/models/chafikboulealam/smart-travel-gemma2-darija

Headers:
  Authorization:  Bearer YOUR_HF_TOKEN
  Content-Type:   application/json

Body (raw JSON):
{
  "inputs": "<start_of_turn>user\nPlanifie-moi 3 jours a Fes.<end_of_turn>\n<start_of_turn>model\n",
  "parameters": {
    "max_new_tokens": 512,
    "temperature": 0.1,
    "do_sample": true,
    "return_full_text": false
  }
}

JavaScript / Next.js Integration

async function generateItinerary(query) {
  const response = await fetch(
    "https://api-inference.huggingface.co/models/chafikboulealam/smart-travel-gemma2-darija",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.HF_TOKEN}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        inputs: `<start_of_turn>user\n${query}<end_of_turn>\n<start_of_turn>model\n`,
        parameters: { max_new_tokens: 512, temperature: 0.1, do_sample: true, return_full_text: false }
      })
    }
  );
  const data = await response.json();
  return JSON.parse(data[0].generated_text);
}

---

Training Details

Hyperparameters

Parameter	Value
LoRA Rank (r)	16
LoRA Alpha	32
LoRA Dropout	0.05
Target Modules	all-linear
Learning Rate	2e-4
Per Device Batch Size	4
Gradient Accumulation Steps	4
Effective Batch Size	16
Max Epochs	5 (with EarlyStoppingCallback, patience=1)
Best Checkpoint	checkpoint-250
Evaluation Strategy	every 50 steps
Training Precision	float16
Hardware	NVIDIA T4 (15GB VRAM)

Training Data

• Primary corpus: atlasia/darija_english - largest bilingual Moroccan Darija dataset
• Synthetic data: 8 Moroccan destinations (Marrakech, Fes, Chefchaouen, Casablanca, Rabat, Agadir, Meknes, Essaouira)
• Prompt format: Gemma-2 chat template with strict JSON system prompt
• Split: 80% train / 10% validation / 10% test

---

Intended Use

• Smart Travel Assistant backend engine
• REST API for Next.js frontend integration
• Travel itinerary generation for Moroccan destinations
• Bilingual French / Moroccan Darija NLP applications

Out-of-scope Use

• Non-Moroccan travel destinations (limited training data)
• Tasks other than itinerary generation
• Real-time booking or reservation systems

---

Important Notes

Gated Model: This model is built on google/gemma-2-2b-it which requires accepting Google's license at huggingface.co/google/gemma-2-2b-it before downloading.

Inference API: The HuggingFace free Serverless Inference API may not be available for this model if it hasn't been assigned an inference provider. Use HF Inference Endpoints for guaranteed production API access.

---

Citation

@misc{smart-travel-gemma2-darija,
  author = {chafikboulealam},
  title = {Smart Travel Assistant - Gemma-2-2b-it Fine-tuned on Darija and French},
  year = {2026},
  publisher = {Hugging Face},
  url = {https://huggingface.co/chafikboulealam/smart-travel-gemma2-darija}
}

License

Apache 2.0 - See LICENSE