# HuMetric

> Entity metrikleri, sinyal işleme ve semantik sorgu için HuMetric API'sini nasıl kullanacağınızı öğrenin.

HuMetric, serbest metin sinyalleri kalibre edilmiş, zamanla sönümlenen varlık metriklerine çeviren bir metrik motorudur. Aşağıdaki her şey tek bir HTTP API üzerinden kullanılır.

Base URL: https://api.gethumetric.com
Auth: Authorization: Bearer hm_live_<your_api_key>

## Kavramlar

- **Entity**: Ölçtüğünüz şey — bir ajan, kullanıcı ya da görev. HuMetric’te her şey bir entity’ye ve ona verdiğiniz ID’ye bağlıdır.
- **Signal**: Bir entity hakkında kanıt: serbest metin veya yapılandırılmış veri. Siz sinyal gönderirsiniz, HuMetric okur.
- **Metric**: HuMetric’in sinyallerden çıkardığı kalibre 0–1 puanı. Her biri bir güven taşır ve zamanla soluklar.
- **Pack**: Puanlama kurallarınız. Bir pack, bir entity tipi için hangi metriklerin çıkarılacağını tanımlar — bir kez tanımlayın, hep kullanın.
- **Güven**: HuMetric’in bir değerden ne kadar emin olduğu. Bir kez yazılır, sonradan değiştirilmez — ama kanıt eskidikçe ağırlığı azalır, yani bayat bir skor sessizce sayılmaz olur.
- **Rıza**: Bir pack, metriği hassas olarak işaretleyebilir. O değerler, varlık ilgili rıza kapsamını verene kadar gizli kalır; rıza geri çekildiği anda yeniden kaybolur.

## Dört çağrıda başlangıç

1. `POST /v1/packs` — Bir entity tipi için neyi ölçeceğini HuMetric’e söyleyin — ör. ajanlar için code_quality ve helpfulness.
2. `POST /v1/entities` — Takip edeceğiniz şeyi kaydedin. Entity yoksa sinyaller reddedilir.
3. `POST /v1/signals` — Olaylar gerçekleştikçe kanıt gönderin. HuMetric metrikleri arka planda çıkarır ve günceller.
4. `GET /v1/entities/{id}/metrics` — Bir entity’nin canlı metriklerini çekin ya da hepsi arasında düz metinle sorgu yapın.

## Dokümanlar

- [Tam API referansı (düz metin)](https://gethumetric.com/llms-full.txt): Referansın tamamı düz metin olarak: kavramlar, kurallar, her uç ve yanıtı, hatalar, limitler.
- [API referansı (HTML)](https://gethumetric.com/docs)
- [OpenAPI](https://api.gethumetric.com/openapi.json): API’nin kendi servis ettiği makine-okunur spec. Çoğu rota orada yanıt şeması bildirmiyor, dolayısıyla yanıt gövdeleri yalnızca bu sayfada eksiksiz.

## Yazılar

- [Çağrı merkezleri için hazır Metric Pack](https://gethumetric.com/blog/cagri-merkezleri-icin-hazir-metric-pack): Yedi metrikli gerçek bir pack, KVKK rıza kapısı ve gerçek bir çalıştırmanın sayıları.
- [Pack Wizard ile bayi kayıp riskini ölçmek](https://gethumetric.com/blog/pack-wizard-ile-bayi-kayip-riski-olcmek): Neyi ölçeceğinizi bilmiyorsanız: düz bir tarifden çalışan bir pack üretmek.
- [Bayi ziyaret notlarından otomatik skor](https://gethumetric.com/blog/bayi-ziyaretlerini-otomatik-skorlama): Serbest metin saha notlarını izlenebilir performans metriklerine çevirmek.
- [Neden zamanla sönümlenen metrikler?](https://gethumetric.com/blog/statik-skor-yerine-zamanla-sonumlenen-metrikler): confidence ile effective_confidence farkı ve bayat kanıtın neden sessizce ağırlığını yitirmesi gerektiği.

## Bilinmesi gerekenler

Bu kuralların atıfta bulunduğu tablolar (camelCase kabul edilen alanlar, uç başına tavanlar) https://gethumetric.com/llms-full.txt içinde.

- **Yazma işlemleri asenkron**: POST /v1/signals daha hiçbir iş yapılmadan 202 ile bir signal_id ve trace_url döner. Döndüğü durum "received" — asla "queued" değil. Çıkarım arka planda çalışır ve sinyali "completed" ya da "failed" durumuna taşır; yeniden denenen bir sinyal "received"a geri döner. Metrikler, onları üreten çağrının içinde asla hazır değildir; sinyali yoklayın ya da varlığı yeniden okuyun.
- **Sayfalama**: Liste uçlarının çoğu limit ve offset alır ve items, total, limit, offset döner — ama hepsi değil, bu yüzden aşağıda uç uç şekle bakın. Metrik geçmişi items yerine points döner. GET /v1/packs, GET /v1/consent/{entity_id} ve GET /v1/metrics/pending-review zarfsız, sayfalamasız çıplak bir JSON dizisi döner. GET /v1/api-keys ise total olmadan {api_keys: […]} döner. limit kabul eden yerlerde tavanın üstünü istemek reddedilmez, sessizce kırpılır.
- **Zaman damgaları**: Giren çıkan bütün zaman damgaları ISO 8601. UTC gönderin; saat dilimi olmayan bir değer UTC kabul edilir. occurred_at gelecekte olamaz.
- **Aynı sinyali yeniden göndermek**: İdempotanlık bir gövde alanı değil, Idempotency-Key istek başlığıdır. Aynı varlık için aynı başlık değerini 24 saat içinde tekrar gönderirseniz kuyruğa ikinci bir kayıt girmez; 200 ile orijinal sinyal ve metrikleri döner — bir webhook denemesini güvenli kılan budur. Dikkat edilecek iki nokta var. external_id tek başına bunu sağlamaz: tekrar kontrolü yalnızca başlık varken çalışır ve ikisi de aynı tekil sütuna yazdığı için, o varlık için daha önce kullandığınız bir external_id’yi yeniden göndermek orijinali döndürmez, 500 ile başarısız olur. 24 saatlik pencere geçtikten sonra tekrarlanan bir başlık değeri için de aynısı geçerlidir. Yani bir idempotanlık değerini varlık başına günde tek kullanımlık sayın: başlık olarak gönderin, tekil tutun ve dünkünü yeniden kullanmayın.
- **confidence ile effective_confidence**: confidence o an kaydedilen değerdir — grafiğe çizilecek dürüst çizgi. effective_confidence ise okuma anında, 365 günlük yarı ömürle üstel zamansal sönümü uygular: o kanıtın bugün hâlâ ne ettiği. İkisi birbirinin yerine geçmez; sıralamayı effective ile yapın, grafiği ham değerle çizin. POST /v1/signals sonuçları ile GET /v1/metrics/pending-review yalnızca ham confidence taşır.
- **Alan adlandırma**: Yanıtlar her zaman snake_case. İstekler de büyük ölçüde snake_case: camelCase yalnızca aşağıda listelenen belirli alanlarda kabul edilir, çünkü her alias bir adlandırma kuralıyla değil elle eklenmiş. Listede olmayan her şey 422 ile reddedilir — insanların ilk çarptığı yer POST /v1/signals üzerindeki entityId, entityType ve externalId. Her yerde snake_case gönderirseniz bunların hiçbiri sizi ilgilendirmez.