KARARDEVELOPER INFRASTRUCTURE
DEVELOPER DOCUMENTATION

İlk isteğinizi bağlayın.

POST /v1/route mesaj, tools, context, agents ve history kabul eder. /v1/chat/completions OpenAI istemcileri içindir.

Authorization: Bearer $KARAR_API_KEY
Content-Type: application/json

Kayıt → yönetici onayı → proje ve API key → ilk istek. Anahtarın düz hâli yalnız oluşturulduğunda gösterilir.

06 / INTEGRATE

Agent’ınızın içine. Yeni bir arayüzün değil.

Hesap oluşturun, yönetici onayından sonra API key alın ve kendi tool şemalarınızla başlayın.

  1. Hesap ve erişim
  2. Tool şemaları ve bağlam
  3. Kararı doğrula, uygulamanda çalıştır
Entegrasyon rehberi ↗
Python SDK
from karar_router import Router

tools = [{"type": "function", "function": {
    "name": "get_order_status", "description": "Siparişin durumunu sorgular.",
    "parameters": {"type": "object", "properties": {
        "order_id": {"type": "string", "description": "Sipariş numarası"}},
        "required": ["order_id"]}}}]
message = "ORD-48291 siparişimin durumunu kontrol et."

# Ağırlıklar özel: HF erişimi (HF_TOKEN) ya da yerel klasör gerekir.
router = Router.from_pretrained("saturday-labs/karar-global")
result = router.route(message, tools, context="Bugün: 20 Kasım 2026")
print(result)

Örnekler entegrasyon iskeletidir. tools ve order_status kendi uygulamanızda tanımlanmalıdır; API key yalnız ortam değişkeninden okunur.

04 / EVALUATION

Sonuçlar. Güçlü ve zayıf yanlarıyla.

Kaynak: yerel model kartındaki raporlanan değerlendirmeler. Bu sayfa için yeniden çalıştırılmadı.

Benchmark / metricKARAR ~180MFunctionGemma 270M
BFCL-TR · simple / multiple36 / 4027 / 28
BFCL · simple / multiple60 / 6058 / 50
BFCL · live simple / multiple40 / 3930 / 27
BFCL · irrelevance8669
BFCL · live irrelevance5981
BFCL · live relevance8367
BFCL · parallel / live parallel0 / 036 / 6
When2Call · strict, comparison subset6159
When2Call · missing counts as ask, full set7859
Mobile Actions · tool accuracy9786
Mobile Actions · exact match5658
Mobile Actions · invented argument ↓019
Agent tasks · 16 end-to-end scenarios13 / 1610 / 16

Görev sayısı belirtilen satır dışında değerler yüzde puandır. When2Call strict karşılaştırma alt kümesidir; esnek puan tam testten gelir (tam test strict: 59). Bu iki satır doğrudan aynı örnek kümesi değildir.

Seen / never-seen tools

SetToolExact
Seen95.6%84.0%
Never-seen91.3%71.9%
Never-seen · 20–50 tools88.9%71.2%
Never-seen sectors94.1%77.4%

Ölçümün sınırları

Model kartı aynı örnekler, aynı puanlama ve batch 1 karşılaştırması bildiriyor. Donanım modeli, sürüm sabitlemesi ve tam ham karşılaştırma kayıtları mevcut belgelerde bulunamadı. CPU/GPU p50 hız değerlerini bu nedenle yayınlamıyoruz.

Parallel benchmark aynı tool’un farklı değerlerle tekrarlanmasını içerir; KARAR aynı tool’u bir turda yalnız bir kez seçer.

Kaynak ve metodoloji ↗

Kaynaklar ve değerlendirme koşulları

Model ve değerlendirme tabloları model_karti_karar_global.md kaynağından alınmıştır. Mimari model.py, çıkarım router.py / core.py, entegrasyonlar karar_router/README.md ve tests/test_sdk.py üzerinden kontrol edilmiştir.

Açıkça belirtilen günlük örnek, localhost inference API’sinin gerçek yanıtıdır; tüm 40 şema tek istekte verilmiştir. Seçim animasyonu bu kaydın yeniden gösterimidir, canlı inference değildir.

Benchmark donanımı ve tam ham karşılaştırma kayıtları sağlanmadığı için hız karşılaştırması yayınlanmamıştır. Model kartı skorları bağımsız bir ölçüm iddiası değildir.

Model card / source
---
language: [tr, en]
library_name: pytorch
tags: [function-calling, tool-use, router, agents, turkish, small-model]
---

# karar-global

**A Turkish-first, ~180M-parameter tool router for AI agents.** Given a user message and a list of available
tools/agents, karar-global decides which tool(s) to call, fills in the arguments, and says what is missing — in
about **24 ms on a GPU and ~180 ms on a CPU**. It never invents tool or parameter names, and it is built to not
invent argument values.

karar-global is trained **from scratch**: our own tokenizer, our own pretraining, and our own fine-tuning data
pipeline. It is not a fine-tune of an existing LLM.

## What it does

| Decision | How |
|---|---|
| Agent | picked among the given agents (with a probability) |
| Tool | picked step by step among the candidates + "no tool"; multiple different tools in one turn |
| No-tool type | chat / unclear (ask) / out of scope / reasoning / task done |
| Parameter present? | separate probability per parameter |
| Enum values | picked among the allowed options |
| Free values | generated by a small decoder that may only copy from the context (message, history, tool results, date, schema). Values not supported by the context are rejected and reported as `missing` |

Example output (`alanlar="en"`):

```json
{"tool": "siparis_iptal", "arguments": {"siparis_no": "12345", "neden": "vazgectim"},
 "missing": [], "param_probs": {"siparis_no": 1.0, "neden": 1.0}, "confidence": 0.99}
```

```json
{"tool": "siparis_iptal", "arguments": {}, "missing": ["siparis_no"], "confidence": 0.99}
```

```json
{"tool": null, "no_tool_type": "chat", "confidence": 1.0}
```

Output formats: our own format (above), **OpenAI** (`tool_calls`) and **Google ADK / Gemini** (`function_call`),
so it plugs into LangGraph, ADK or any OpenAI-compatible agent. Calls with a missing required value are not put in
`tool_calls`; they are reported in `metadata.missing` so the agent can ask the user. Field names are available in
English (`missing`, `confidence`, ...) or Turkish (`eksik`, `guven`, ...).

## Model

| | |
|---|---|
| Architecture | encoder-decoder transformer with selection heads (agent / tool / no-tool type / parameter / enum) and a copy-constrained value decoder |
| Size | 169M backbone + 11M heads |
| Tokenizer | own 48K BPE, Turkish-optimized |
| Context | up to 8,192 tokens; tested with 2–50 candidate tools |
| Languages | Turkish and English (equal quality); limited coverage of 15 other languages |

## Benchmarks

All models were run by us on **the same examples with the same scoring**, single request at a time (batch 1), on
the same hardware.

### Compared with FunctionGemma 270M

| Benchmark | karar-global (180M) | FunctionGemma (270M) |
|---|---|---|
| BFCL-TR simple / multiple (BFCL accuracy) | **36 / 40** | 27 / 28 |
| BFCL simple / multiple | **60 / 60** | 58 / 50 |
| BFCL live simple / live multiple | **40 / 39** | 30 / 27 |
| BFCL irrelevance (no call when no tool fits) | **86** | 69 |
| BFCL live irrelevance | 59 | **81** |
| BFCL live relevance | **83** | 67 |
| BFCL parallel / live parallel ¹ | 0 / 0 | **36 / 6** |
| When2Call (NVIDIA), strict ² | **61** | 59 |
| When2Call, missing info reported in `missing` counts as "ask" ² | **78** | 59 |
| Mobile Actions: correct tool | **97** | 86 |
| Mobile Actions: exact match | 56 | **58** |
| Mobile Actions: hallucinated argument (lower is better) | **0** | 19 |
| Agent scenarios (LangGraph and ADK, 16 tasks end to end) | **13 / 16** | 10 / 16 |
| Latency, GPU, p50 | **24 ms** | 400 ms |
| Latency, CPU, p50 | **181 ms** | 2,754 ms |

¹ *Parallel* means calling the **same** tool several times with different values in one turn. karar-global calls
each tool at most once per turn by design; tools that accept a list (e.g. `cities: ["İstanbul", "İzmir"]`) are
supported.
² When2Call expects "don't call, ask" when information is missing. karar-global instead selects the tool and
reports the missing required values in `missing`, which is how it asks. The second row counts that as asking.
(Strict score on the comparison subset; the lenient score is from the full test set, strict 59 there.)

### Internal evaluation (held-out)

| Set | Tool decision | Exact match (tool + all values) | Value invented for a parameter the user did not give (lower is better) |
|---|---|---|---|
| Seen tools | 95.6 | 84.0 | 2.3 |
| Never-seen tools | 91.3 | 71.9 | 5.5 |
| Never-seen tools, 20–50 candidates | 88.9 | 71.2 | 5.1 |
| Never-seen business sectors | 94.1 | 77.4 | 6.0 |

On the same seen/never-seen sets FunctionGemma scores 23 / 10 exact match and invents values 47 / 49% of the
time (comparison subsets).

## Limitations

- Does not call the **same** tool more than once in a turn (see ¹).
- Sometimes calls a tool for requests that no tool can serve (BFCL live irrelevance 59).
- Values that must be **computed** from the message ("raise my 6 rating by 2" → 8) are often wrong.
- Multi-step loops and multi-tool turns are its weakest areas (exact match ~55–60%).
- `confidence` is somewhat over-confident on never-seen tools.

## Recommended use

karar-global is a router: put it in front of your agent or LLM. As with any tool-calling model:

- If `missing` is not empty, ask the user for the missing information.
- If `confidence` is low, don't call; fall back or ask.
- Confirm irreversible actions (payment, cancel, delete) with the user.

## Usage

```python
import sys; sys.path.insert(0, "kod")
import sft_final as SF

t = SF.Tahminci("sft-final.pt", "tokenizer/tokenizer.json")
tools = [{"name": "siparis_iptal", "description": "Kargoya verilmemiş siparişi iptal eder",
          "parameters": [{"path": "siparis_no", "type": "string", "description": "sipariş numarası",
                          "enum": None, "required": True}]}]
t.tahmin("12345 nolu siparişimi iptal et", tools, "Bugün: 19 Kasım 2026, Perşembe", alanlar="en")
# OpenAI-compatible assistant message:   bicim="openai"   → {"role": "assistant", "tool_calls": [...], "metadata": {...}}
# Google ADK / Gemini:                   bicim="adk"      → {"role": "model", "parts": [{"function_call": ...}], ...}
```

A lightweight `pip` package and an HTTP API are planned.

---

## Türkçe özet

**karar-global**, AI agent'lar için Türkçe öncelikli, ~180M parametreli bir tool router'ı. Kullanıcı mesajı ve
eldeki tool listesini alır; hangi tool'un çağrılacağına karar verir, değerleri doldurur ve eksik bilgiyi söyler.
GPU'da ~24 ms, CPU'da ~180 ms. Tool ve parametre adlarını uydurmaz; değerleri yalnızca mesajdan ve bağlamdan
kopyalar. Sıfırdan eğitildi: kendi tokenizer'ı, kendi ön eğitimi ve kendi ince ayar verisi. Hazır bir LLM'in ince
ayarı değil.

FunctionGemma 270M ile aynı örnekler ve aynı puanlamayla yapılan kıyas yukarıdaki tabloda. Bilinen sınırlar:
aynı tool'u bir turda birden çok kez çağırmaz, uygun tool olmayan bazı isteklerde yine de tool çağırabilir ve
hesap gerektiren değerlerde zorlanır.