osmanozaydin/Mihfar-Edge-1B-Agentic

🧠 Mihfar Edge 1B Agentic

Lightweight Bilingual (EN/TR) Edge Language Model with Native Agentic & ReAct Reasoning

🌐 Language / Dil: English | 🇹🇷 Türkçe Açıklama İçin Tıklayın

---

🌟 What is Mihfar Edge?

Mihfar Edge 1B Agentic is a lightweight, open-source 1.045 Billion Parameter (1.045B) causal language model designed and trained from scratch using PyTorch.

It features native bilingual capabilities in English and Turkish, with built-in Agentic reasoning (autonomous tool calling, multi-step ReAct planning, and internal <|think|> scratchpad deliberation).

Optimized for consumer-grade GPUs (RTX 3060, RTX 4060, Apple Silicon M-series, or CPU), it operates efficiently with under 3 GB of VRAM, delivering fast, responsive, and private on-device intelligence.

---

🚀 Key Highlights & Capabilities

• 1.045B Parameter Architecture: 28 layers, Grouped-Query Attention (GQA 4:1), and SwiGLU feed-forward networks.
• Bilingual Mastery (EN / TR): Fluent conversations, precise visual/textual Q&A, and strict instruction adherence in both English and Turkish.
• Native Agentic & Function Calling Support:
  • <|think|> ... <|/think|>: Internal deliberate reasoning and step-by-step planning (Chain-of-Thought / ReAct).
  • <|tool_call|> ... <|/tool_call|>: Direct structured JSON tool and API invocation.
  • <|tool_response|> ... <|/tool_response|>: Environmental feedback interpretation and final answer synthesis.
• Custom 49K BPE Tokenizer: Byte-Level BPE vocabulary specifically pre-trained on Turkish morphology, English corpora, and JSON schema syntax.
• Stable Training & Inference: QK-RMSNorm, RoPE ($\theta = 500,000$), and Value Residual (ResFormer) skip connections to eliminate attention sink degradation.

---

📊 Architecture & Model Specifications

Parameter	Specification
Total Parameters	1,045,142,838 (~1.05B)
Hidden Layers (num_hidden_layers)	28
Hidden Size (hidden_size)	1792
SwiGLU Intermediate Size	4864
Attention Heads	28 Query, 7 KV (4:1 GQA)
Context Window (max_seq_len)	2048 tokens
Vocabulary Size (vocab_size)	49,152 (Byte-Level BPE)
Weight Serialization	safetensors (Zero-copy, safe loading)

---

🛠️ Installation

Clone the repository and install dependencies:

git clone https://huggingface.co/osmanozaydin/Mihfar-Edge-1B-Agentic
cd Mihfar-Edge-1B-Agentic
pip install -r requirements.txt

---

💻 Python Quickstart

1. Direct Conversational Generation

import torch
from mihfar_edge import MihfarEdgeModel, MihfarEdgeTokenizer

device = "cuda" if torch.cuda.is_available() else "cpu"

# Load Model and Tokenizer
tokenizer = MihfarEdgeTokenizer.load(".")
model = MihfarEdgeModel.from_pretrained(".", device=device)

# Prepare Chat Template
messages = [
    {"role": "system", "content": "You are Mihfar Edge, an intelligent and helpful AI assistant fluent in English and Turkish."},
    {"role": "user", "content": "Explain why edge AI models are important for privacy and low latency."}
]
prompt = tokenizer.format_chat(messages, add_generation_prompt=True)
input_ids = torch.tensor([[tokenizer.bos_id] + tokenizer.encode(prompt)], device=device)

# Generate Response
with torch.inference_mode():
    output_ids = model.generate(input_ids, max_new_tokens=200, temperature=0.4, top_p=0.9)

response = tokenizer.decode(output_ids[0, input_ids.shape[1]:].tolist(), skip_special_tokens=True)
print("Mihfar Edge:", response)

---

2. Autonomous Agent Mode (Tool & Function Calling)

The model can automatically invoke tools (such as calculators, weather APIs, or device telemetry) and deliberate using <|think|>:

import torch
from mihfar_edge import MihfarEdgeModel, MihfarEdgeTokenizer, MihfarAgentRuntime

device = "cuda" if torch.cuda.is_available() else "cpu"
tokenizer = MihfarEdgeTokenizer.load(".")
model = MihfarEdgeModel.from_pretrained(".", device=device)

# Start Agent Runtime
agent = MihfarAgentRuntime(model, tokenizer, device=torch.device(device))

# Ask question requiring tool use
query = "If I purchase 15 units of an item priced at $125 each with an 8% tax rate, what is the total cost?"
result = agent.run_agent_turn(query, lang="en")

# Print reasoning trace and final answer
for step in result["trace"]:
    print(f"[{step['role'].upper()}]: {step['content']}\n")

---

3. Interactive CLI Testing

# Bilingual interactive chat:
python inference.py --interactive

# Autonomous agent mode with live tool calling:
python inference.py --interactive --agent

---

🇹🇷 Türkçe Model Kartı (Tıklayarak Genişletin / Click to Expand)

Mihfar Edge 1B Agentic

Mihfar Edge 1B Agentic, sıfırdan PyTorch ile tasarlanmış ve eğitilmiş, 1.045 Milyar Parametreli (1.045B), Türkçe ve İngilizce çift dilli, yerel Agentic (Araç Çağırma, <|think|> ReAct Akıl Yürütme) yeteneklerine sahip açık kaynaklı bir uç (Edge) yapay zeka dil modelidir.

Tüketici sınıfı GPU'larda (RTX 3060, 4060, Apple Silicon veya CPU) yerel olarak düşük VRAM tüketimiyle (<3 GB) akıcı ve hızlı çalışmak üzere optimize edilmiştir.

---

🚀 Öne Çıkan Özellikler

• 1.045B Parametre Mimarisi: 28 katmanlı, Grouped-Query Attention (GQA 4:1) ve SwiGLU tabanlı derin mimari.
• Çift Dilli (TR / EN): Türkçe ve İngilizce dillerinde akıcı sohbet, soru-cevap ve talimat takibi.
• Yerel Agentic Desteği:
  • <|think|> ... <|/think|> etiketleri ile adım adım içsel akıl yürütme (Chain-of-Thought / ReAct).
  • <|tool_call|> ... <|/tool_call|> ile yapılandırılmış JSON fonksiyon/araç çağırma.
  • <|tool_response|> ... <|/tool_response|> ile araç çıktılarını değerlendirme ve nihai yanıta varma.
• Özel 49K BPE Tokenizer: Türkçe morfolojisine, İngilizceye ve JSON şemalarına özel eğitilmiş Byte-Level BPE sözlüğü.
• Kararlı Eğitilebilirlik & Çıkarım: QK-RMSNorm, RoPE ($\theta = 500,000$), Value Residual (ResFormer) bağlantıları.

---

📊 Model Parametreleri ve Mimari Detayları

Özellik	Değer
Toplam Parametre	1,045,142,838 (~1.05B)
Katman Sayısı (num_hidden_layers)	28
Gizli Boyut (hidden_size)	1792
SwiGLU Ara Boyut (intermediate_size)	4864
Dikkat Başlıkları (Attention Heads)	28 Query, 7 KV (4:1 GQA)
Bağlam Uzunluğu (max_seq_len)	2048 token
Kelime Dağarcığı (vocab_size)	49,152 (Byte-Level BPE)
Ağırlık Formatı	safetensors (Zero-copy, güvenli serileştirme)

---

🛠️ Kurulum (Installation)

Depoyu klonlayıp gerekli kütüphaneleri yükleyin:

git clone https://huggingface.co/osmanozaydin/Mihfar-Edge-1B-Agentic
cd Mihfar-Edge-1B-Agentic
pip install -r requirements.txt

---

💻 Python ile Kullanım

1. Doğrudan Sohbet ve Metin Üretimi

import torch
from mihfar_edge import MihfarEdgeModel, MihfarEdgeTokenizer

device = "cuda" if torch.cuda.is_available() else "cpu"

# Model ve Tokenizer'ı yükleyin
tokenizer = MihfarEdgeTokenizer.load(".")
model = MihfarEdgeModel.from_pretrained(".", device=device)

# Sohbet şablonunu hazırlayın
messages = [
    {"role": "system", "content": "Sen Mihfar Edge adlı Türkçe ve İngilizce bilen yardımcı bir yapay zekasın."},
    {"role": "user", "content": "Edge yapay zeka modelleri neden önemlidir?"}
]
prompt = tokenizer.format_chat(messages, add_generation_prompt=True)
input_ids = torch.tensor([[tokenizer.bos_id] + tokenizer.encode(prompt)], device=device)

# Yanıt üretin
with torch.inference_mode():
    output_ids = model.generate(input_ids, max_new_tokens=200, temperature=0.4, top_p=0.9)

yanit = tokenizer.decode(output_ids[0, input_ids.shape[1]:].tolist(), skip_special_tokens=True)
print("Mihfar Edge:", yanit)

---

2. Otonom Agentic Modu (Araç Çağırma / Function Calling)

Model, hesap makinesi, hava durumu, cihaz telemetrisi gibi araçları otomatik olarak çağırabilir ve <|think|> ile planlama yapabilir:

import torch
from mihfar_edge import MihfarEdgeModel, MihfarEdgeTokenizer, MihfarAgentRuntime

device = "cuda" if torch.cuda.is_available() else "cpu"
tokenizer = MihfarEdgeTokenizer.load(".")
model = MihfarEdgeModel.from_pretrained(".", device=device)

# Agent runtime'ını başlatın
agent = MihfarAgentRuntime(model, tokenizer, device=torch.device(device))

# Soruyu yöneltin
soru = "Tanesi 1250 TL olan bir üründen 15 adet alırsam ve %20 KDV eklenirse toplam ne kadar öderim?"
sonuc = agent.run_agent_turn(soru, lang="tr")

# Adımları ve nihai cevabı yazdırın
for adim in sonuc["trace"]:
    print(f"[{adim['role'].upper()}]: {adim['content']}\n")

---

3. Komut Satırından Hızlı Test (CLI)

# Çift dilli interaktif sohbet:
python inference.py --interactive

# Otonom araç çağıran Agent modu:
python inference.py --interactive --agent

---

📈 Eğitim Aşamaları

Model NVIDIA RTX 4060 Ti üzerinde 14 farklı Türkçe, İngilizce ve Agentic veri seti ile 3 aşamada eğitilmiştir:

1. Bilingual Pre-training: Temel dil ve mantık kurma (~88.5M token).
2. Instruction SFT: Çift dilli talimat takip etme.
3. Agentic Tool Mastery: Multi-turn ReAct ve JSON araç çağırma yetkinliği (Val Perplexity: 2.82).

---

📜 Lisans

Bu proje MIT lisansı ile dağıtılmaktadır. Hem ticari hem de kişisel projelerinizde serbestçe kullanabilirsiniz.

---

📜 License

This project is licensed under the MIT License. Free for both commercial and personal use.