Intentum Dokümantasyonu (TR)

Bu sayfayı neden okuyorsunuz? Bu sayfa Intentum’un ne olduğunu, ne işe yaradığını ve nereden başlamanız gerektiğini anlatır. Konsepte hiç aşina değilseniz doğru yerdesiniz; kurulum ve ilk deneme adımları da burada.

Intentum nedir? (Tek cümle)

Intentum, uygulamadaki kullanıcı ve davranış olaylarını analiz edip niyet tahmin eden ve bu niyete göre otomatik karar (izin, uyarı, engel vb.) almanızı sağlayan bir kütüphanedir. Örneğin şüpheli bir hesap ele geçirme girişimini tespit edip engelleyebilir veya sık yapılan bir işlemi hızlandırabilir.

Günlük benzetme: Sisteminizi koruyan bir güvenlik görevlisi gibi düşünün. Görevli izler (kameralar, sensörler), yorumlar (gelen tanıdık mı, hareketler şüpheli mi?) ve karar verir (kapıyı açar, uyarır, güvenliği arar). Intentum da bu üç adımı yazılımda otomatikleştirir: Gözlemle (Observe) → Tahmin et (Infer) → Karar ver (Decide).

Intentum nedir? (Detay)

Intentum, davranışın tam deterministik olmadığı sistemler için intent odaklı bir yaklaşımdır: klasik BDD’deki gibi sabit senaryo adımları yerine, ne olduğunu gözlemlersin, kullanıcının veya sistemin intent’ini (isteğe bağlı AI embedding’leriyle) çıkarırsın ve policy kurallarıyla ne yapacağına karar verirsin (Allow, Observe, Warn, Block).

Behavior Space — Olayları kaydedersin (örn. login, retry, submit). Sabit “Given/When/Then” adımları yok.
Intent — Model bu davranıştan intent ve güven (High / Medium / Low) çıkarır.
Policy — Kurallar intent’i kararlara eşler: örn. “yüksek güven → Allow”, “çok fazla retry → Block”.

Yani: gözlemle → çıkar → karar ver. Akışlar değişkense, AI adapte oluyorsa veya adımlardan çok intent önemliyse kullanışlıdır.

AI ile ne yapıyoruz?

Intentum’da Infer adımı isteğe bağlı AI (embedding) kullanır: davranış anahtarlarını (örn. user:login, analyst:prepare_esg_report) vektörlere çevirir, benzerlik skorundan güven seviyesi (High / Medium / Low / Certain) ve sinyalleri üretir.

Adım	Ne olur
Embedding	Her `actor:action` anahtarı bir embedding sağlayıcı ile vektör + skor alır. Mock (yerel/test) = hash tabanlı, deterministik; gerçek sağlayıcı (OpenAI, Gemini, Mistral, Azure, Claude) = anlamsal vektörler, aynı davranış farklı modellerde hafif farklı güven verebilir.
Similarity	Similarity engine tüm embedding’leri tek bir skora indirger (örn. ortalama). Bu skor güven seviyesine dönüştürülür.
Intent	LlmIntentModel bu skordan Intent (Confidence + Signals) üretir; policy bu intent’e göre Allow / Observe / Warn / Block verir.

Örneklerde genelde Mock kullanılır (API anahtarı yok). Gerçek AI ile denemek için ortam değişkeniyle bir sağlayıcı seçip aynı akışı çalıştırabilirsin; bkz. Sağlayıcılar ve Kurulum – gerçek sağlayıcı. Samples tam showcase uygulamaları (infer, explain, explain-tree, playground, analytics, timeline); examples minimal tek use-case projeleri (fraud-intent, customer-intent, ai-fallback-intent, chained-intent, time-decay-intent, vector-normalization, greenwashing-intent). Şablonlar: dotnet new intentum-webapi, intentum-backgroundservice, intentum-function — bkz. Kurulum – Şablondan oluştur. Örnekler özeti ve Testler özeti doküman sidebar’ında. Intent opsiyonel Reasoning (hangi kural eşleşti veya fallback) içerebilir.

Given/When/Then yerine ne geldi?

Klasik BDD’de Given (ön koşul), When (aksiyon), Then (beklenti) yazarsın. Bu, sabit adımlar ve tek bir pass/fail sonucu varsayar. Intentum Given/When/Then kullanmaz; deterministik olmayan ve intent odaklı sistemlere uyan farklı bir akış kullanır.

BDD (Given/When/Then)	Intentum (yerine gelen)
Given — sabit ön koşullar	Observe — Gerçekten ne olduğunu (login, retry, submit gibi olayları) bir BehaviorSpace içine kaydedersin. Sabit “given” durumu yok; gerçek davranışı yakalarsın.
When — tek aksiyon	Aynı Observe — olaylar “when”dir; `space.Observe(actor, action)` ile eklenir. Birden fazla olay, sıra korunur.
Then — tek assertion, pass/fail	Infer + Decide — model davranıştan intent ve güven (High/Medium/Low) çıkarır, sonra bir policy sonucu belirler: Allow, Observe, Warn veya Block. Yani “then X should be true” yerine “bu davranışa göre intent Y, karar Z” alırsın.

Kısaca: Given/When/Then kalktı; yerine Observe (olayları kaydet) → Infer (intent + güven) → Decide (policy sonucu) var. Ne olduğunu tarif edersin, model intent’i yorumlar, kurallar kararı seçer. Tipler için API Referansı, örnekler için Senaryolar.

Kimler için?

Intentum’u şu durumlarda kullan:

Akışlar deterministik değil veya AI tabanlı.
Sabit pass/fail adımları yerine intent üzerinden düşünmek istiyorsun.
Gözlenen davranıştan policy tabanlı kararlar (allow / observe / warn / block) alman gerekiyor.

Intentum’u atla:

Sistem tam deterministik ve gereksinimler sabit.
Sadece küçük script’ler veya tek seferlik araçlar var; davranış sapması önemsiz.

Öğrenme yolu

Hangi sırayla ilerleyeceğiniz:

Başlangıç — Temel akışı ve Intentum.Core / Runtime / AI’yı öğrenin. → Mimari, Kurulum.
İleri — Policy yazma, senaryolar, gerçek AI sağlayıcı. → Senaryolar, Sağlayıcılar.
Veri — Niyet geçmişini kaydetmek ve analiz etmek. → Kurulum – Repo yapısı, Gelişmiş Özellikler (Analytics).
Gelişmiş — Analytics, Clustering, Explainability, Policy Store vb. → Gelişmiş Özellikler.

Doküman içeriği

Sayfa	Ne bulacaksın
Mimari	Temel akış (Observe → Infer → Decide), paket yapısı, inference pipeline, persistence/analytics/rate-limiting/multi-tenancy akışları (Mermaid diyagramları).
Kitle ve kullanım örnekleri	Proje tipleri, kullanıcı profilleri, düşük/orta/yüksek örnek test senaryoları (AI ve normal), sektör örnekleri.
Kurulum	Gereksinimler, NuGet kurulumu, ilk proje adımları, env var.
API Referansı	Ana tipler (BehaviorSpace, Intent, Policy, sağlayıcılar) ve nasıl uyumlu oldukları.
Sağlayıcılar	OpenAI, Gemini, Mistral, Azure OpenAI, Claude — env var ve DI kurulumu.
Kullanım Senaryoları	Örnek akışlar (tekrarlı ödeme, şüpheli tekrarlar, policy sırası).
CodeGen	CQRS + Intentum proje iskeleti; test assembly veya YAML spec’ten Features üretme.
Test	Birim testleri, coverage, hata senaryoları.
Yerel entegrasyon testleri	`.env` ve script'lerle VerifyAI (tüm sağlayıcılar) veya sağlayıcı bazlı entegrasyon testlerini yerelde çalıştırma.
Coverage	Coverage üretme ve görüntüleme; SonarCloud bulguları ve kalite kapısı.
Benchmark'lar	BenchmarkDotNet: ToVector, Infer, PolicyEngine; çalıştırma ve `./scripts/run-benchmarks.sh` ile doküman güncelleme.
Örnekler özeti	Zorluk (basit / orta / zor) ve gerçek hayat use-case’lerine göre örnekler ve sample’lar.
Testler özeti	Test projeleri, sample linkleri ve birim/entegrasyon testlerini çalıştırma.
Gelişmiş Özellikler	Similarity engine’ler, vektör normalizasyonu, kural tabanlı ve zincirli modeller, fluent API’ler, caching, Intent Timeline, Intent Tree, Context-Aware Policy, Policy Store, Behavior Pattern Detector, Multi-Stage Model, Scenario Runner, stream processing, OpenTelemetry tracing, rate limiting, analytics, middleware, observability, persistence.

5 dakikada ilk deneme (Hızlı başlangıç)

Somut senaryo: Ahmet kullanıcısı 1 dakika içinde: 1) 3 kez giriş denedi (2 başarısız, 1 başarılı), 2) Giriş yaptıktan sonra "submit" aksiyonunu tetikledi. Sistem bu davranışı gözlemleyip niyet ve güven çıkaracak; policy Allow veya Observe kararı verecek.

Çekirdek paketleri yükle

dotnet add package Intentum.Core
dotnet add package Intentum.Runtime
dotnet add package Intentum.AI

Sample’ı çalıştır (API anahtarı gerekmez; mock sağlayıcı kullanır)
```
dotnet run --project samples/Intentum.Sample
```
Minimal “ilk proje” için Kurulum ve ana tipler ile akış için API Referansı oku.

Doğru yaptığınızı nasıl anlarsınız? Çalıştırdıktan sonra konsolda bir güven seviyesi (örn. High, Medium) ve bir karar (Allow, Observe, Warn veya Block) görürsünüz. Örnek: Güven: High, Karar: Allow.

Nasıl yapılır?

İlk senaryoyu nasıl çalıştırırım? — Konsol örneği: dotnet run --project samples/Intentum.Sample (mock sağlayıcı, API anahtarı gerekmez). Tam API ve Blazor UI için dotnet run --project samples/Intentum.Sample.Blazor (Overview, Commerce, Explain, FraudLive, Sustainability, Timeline, PolicyLab, Sandbox). Repo yapısı ve endpoint'ler için Kurulum'a bakın. Örnekler hem klasik (ödeme, giriş, destek, e‑ticaret: sepete ekleme, checkout, ödeme doğrulama) hem ESG (rapor gönderimi, uyumluluk) akışlarını gösterir.
Policy nasıl eklenir? — IntentPolicy oluştur, .AddRule(PolicyRule(...)) ile kuralları sırayla ekle (önce Block, sonra Allow). Çıkarımdan sonra intent.Decide(policy) çağır. Detay için Senaryolar ve API Referansı.
Klasik akışları (ödeme, login, destek) nasıl modellersin? — Olayları space.Observe(actor, action) ile kaydet (örn. "user", "login"; "user", "retry"; "user", "submit"). Model davranıştan intent çıkarır; policy Allow/Observe/Warn/Block verir. Kullanım Senaryoları içinde hem klasik (ödeme, e‑ticaret) hem ESG örnekleri var.
AI ile senaryo nasıl yazılır? — Aynı Observe akışı Mock veya gerçek sağlayıcı (OpenAI, Gemini vb.) ile çalışır; davranış anahtarlarını anlamlı seç, policy'yi güven + sinyallere dayandır. Detay ve ipuçları: Senaryolar – AI ile senaryolar.

Daha fazla örnek ve kural sıralaması için Senaryolar ve Kitle ve kullanım örnekleri.

Global kullanım notları

API anahtarları — Ortam değişkenleri veya secret manager kullan; anahtarları asla commit etme.
Bölge ve gecikme — Sağlayıcı endpoint konumu ve rate limit’leri dikkate al.
Production — Ham sağlayıcı istek/cevaplarını loglama.

Tam API metod imzaları için otomatik üretilen API sitesine bak.

Table of Contents