Giriş

Deterministik olmayan kullanıcı akışları, tekrarlı denemeler (login, ödeme) veya AI tabanlı kararlar söz konusu olduğunda “ne oldu?” sorusundan çok “sistem ne yapmaya çalışıyor?” sorusu öne çıkar.

Intentum, .NET ekosisteminde bu ihtiyacı karşılayan açık kaynak bir kütüphanedir: davranış olaylarını toplar, niyet (intent) ve güven (confidence) çıkarır, policy (politika) kurallarıyla Allow, Observe, Warn, Block gibi kararlar üretir.

Bu yazıda Intentum’un ne olduğunu, hangi mimari problemi çözdüğünü, nasıl kurulup kullanılacağını ve ne zaman tercih edilmemesi gerektiğini teknik detay ve kod örnekleriyle ele alıyorum.

Intentum Nedir?

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.

Klasik BDD (Given/When/Then) tarzı sabit senaryo adımları yerine üç adımlı bir akış kullanır:

Observe (gözlemle) → Infer (çıkar) → Decide (karar ver).

Gözlemle: Olayları BehaviorSpace içine Observe(actor, action) ile kaydedersiniz.
Çıkar: Bir intent modeli (ör. LlmIntentModel) bu davranışı bir Intent ve güven seviyesine (High, Medium, Low, Certain) dönüştürür.
Karar ver: IntentPolicy kuralları ile intent.Decide(policy) çağrısı sonucu Allow, Observe, Warn, Block, Escalate, RequireAuth veya RateLimit kararı alırsınız.

Yani sabit “then X should be true” yerine, davranışa göre çıkarılan intent ve policy sonucu ile çalışırsınız.

Hangi Problemi Çözer?

Intentum, davranışın tam deterministik olmayan sistemler için tasarlanmıştır.

Çözdüğü problem: senaryo bazlı testlerin kırılganlığı ve “ne oldu?” odaklı karar verme yerine “sistem ne yapmaya çalışıyor?” sorusuna cevap verebilmek.

Aşağıdaki tabloda hangi projelerde kullanılması mantıklı, hangilerinde gereksiz olduğu özetleniyor.

Temel Akış ve Mimari

Veri akışı:

BehaviorSpace (olaylar) → IIntentModel.Infer(space) → Intent (güven, sinyaller) → IntentPolicy → PolicyDecision.

Çekirdek tipler:

• BehaviorSpace: Observe(actor, action) ile olayları toplar; ToVector() ile behavior vektörü üretir.
• IIntentModel: LlmIntentModel (embedding + similarity), RuleBasedIntentModel (sadece kurallar), ChainedIntentModel (önce kural, düşük güvende LLM fallback).
• Intent: Confidence (Level, Score), Signals (ağırlıklı davranışlar), opsiyonel Reasoning.
• IntentPolicy: Sıralı PolicyRule listesi; ilk eşleşen kural kazanır. IntentPolicyBuilder ile fluent tanım yapılabilir.

Kurulum ve Yapılandırma

.NET SDK 10.x (veya projenin hedeflediği sürüm) yeterlidir.

Çekirdek paketler:

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

Gerçek embedding API kullanacaksanız bir sağlayıcı paketi ekleyin (ör. Intentum.AI.OpenAI). Sağlayıcı eklemezseniz yerel çalıştırma ve test için MockEmbeddingProvider kullanılır; API anahtarı gerekmez.

Minimal konsol örneği

using Intentum.AI.Mock;
using Intentum.AI.Models;
using Intentum.AI.Similarity;
using Intentum.Core;
using Intentum.Core.Behavior;
using Intentum.Runtime.Policy;

var space = new BehaviorSpace()
    .Observe("user", "login")
    .Observe("user", "retry")
    .Observe("user", "submit");

var model = new LlmIntentModel(
    new MockEmbeddingProvider(),
    new SimpleAverageSimilarityEngine());
var intent = model.Infer(space);

var policy = new IntentPolicy()
    .AddRule(new PolicyRule("AllowHigh",
        i => i.Confidence.Level is "High" or "Certain",
        PolicyDecision.Allow))
    .AddRule(new PolicyRule("ObserveMedium",
        i => i.Confidence.Level == "Medium",
        PolicyDecision.Observe));

var decision = intent.Decide(policy);
Console.WriteLine($"Güven: {intent.Confidence.Level}, Karar: {decision}");

ASP.NET Core DI

Program.cs içinde servis kaydı ve (isteğe bağlı) davranış gözlem middleware’i:

using Intentum.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddIntentum();
// Gerçek sağlayıcı için: builder.Services.AddIntentumOpenAI(OpenAIOptions.FromEnvironment());

var app = builder.Build();
app.UseIntentumBehaviorObservation(new BehaviorObservationOptions
{
    Enabled = true,
    GetActor = ctx => "http",
    GetAction = ctx => $"{ctx.Request.Method}_{ctx.Request.Path.Value?.Replace("/", "_")}"
});

Kod Örnekleri

Basit intent ve policy

Yukarıdaki minimal örnek zaten basit intent akışını gösteriyor. Fluent policy builder ile Block, Escalate, RequireAuth, Allow zinciri:

var policy = new IntentPolicyBuilder()
    .Block("ExcessiveRetry",
        i => i.Signals.Count(s => s.Description.Contains("retry", StringComparison.OrdinalIgnoreCase)) >= 3)
    .Escalate("LowConfidence", i => i.Confidence.Level == "Low")
    .RequireAuth("SensitiveAction", i => i.Signals.Any(s => s.Description.Contains("sensitive")))
    .Allow("HighConfidence", i => i.Confidence.Level is "High" or "Certain")
    .Build();
var decision = intent.Decide(policy);

Policy ile davranış doğrulama (retry eşiği)

Intentum’da “validation” klasik anlamda değil; policy kuralları ile davranışın kabul edilirliği kontrol edilir. Örneğin aşırı retry’da Block:

var space = new BehaviorSpace()
    .Observe("user", "login")
    .Observe("user", "retry")
    .Observe("user", "retry")
    .Observe("user", "retry");

var intent = model.Infer(space);
var policy = new IntentPolicy()
    .AddRule(new PolicyRule("ExcessiveRetryBlock",
        i => i.Signals.Count(s => s.Description.Contains("retry", StringComparison.OrdinalIgnoreCase)) >= 3,
        PolicyDecision.Block))
    .AddRule(new PolicyRule("AllowHigh", i => i.Confidence.Level is "High" or "Certain", PolicyDecision.Allow))
    .AddRule(new PolicyRule("ObserveMedium", i => i.Confidence.Level == "Medium", PolicyDecision.Observe));

var decision = intent.Decide(policy);

Kural sırasının önemi

Policy kuralları ekleme sırasına göre değerlendirilir; ilk eşleşen kural kazanır. Block kurallarını Allow’dan önce ekleyin ki şüpheli davranışlar engellensin, normal akışlar ise yalnızca engellenmediyse Allow alsın.

Cross-cutting: Logging ve Observability

Intentum.Logging ile Serilog entegrasyonu,
Intentum.Observability ile OpenTelemetry metrikleri.

Örnek: intent modelini metrik saran wrapper ile kullanmak ve karar sonrası metrik kaydı.

using Intentum.Observability;

var model = new ObservableIntentModel(
    new LlmIntentModel(embeddingProvider, new SimpleAverageSimilarityEngine()));
var intent = model.Infer(space);
var decision = intent.DecideWithMetrics(policy);

Intent geçmişi ve persistence

Intentum’da doğrudan “transaction” yok,

İstenirse IIntentHistoryRepository.SaveAsync ile intent ve kararı saklayabilirsiniz.
EF Core, Redis veya MongoDB paketleri ile persistence eklenir.

Web API endpoint (infer)

Controller’da IIntentModel ve policy inject edilip, gelen olay listesinden BehaviorSpace oluşturulur;

Infer ve Decide çağrılır:

[ApiController]
[Route("api/[controller]")]
public class IntentController : ControllerBase
{
    private readonly IIntentModel _model;
    private readonly IntentPolicy _policy;

    public IntentController(IIntentModel model, IntentPolicy policy)
    {
        _model = model;
        _policy = policy;
    }

    [HttpPost("infer")]
    public IActionResult Infer([FromBody] InferRequest request)
    {
        var space = new BehaviorSpace();
        foreach (var e in request.Events)
            space.Observe(e.Actor, e.Action);
        var intent = _model.Infer(space);
        var decision = intent.Decide(_policy);
        return Ok(new { intent.Confidence, intent.Signals, Decision = decision });
    }
}

public record InferRequest(List<EventDto> Events);
public record EventDto(string Actor, string Action);

Unit test (Intentum.Testing)

Test projesine Intentum.Testing ekleyip TestHelpers ve assertion extension’larını kullanın:

using Intentum.Testing;
using Intentum.Core.Behavior;
using Intentum.Runtime.Policy;

var model = TestHelpers.CreateDefaultModel();
var policy = TestHelpers.CreateDefaultPolicy();
var space = TestHelpers.CreateSimpleSpace();

var intent = model.Infer(space);
var decision = intent.Decide(policy);

BehaviorSpaceAssertions.ContainsEvent(space, "user", "login");
IntentAssertions.HasConfidenceLevel(intent, "High");
PolicyDecisionAssertions.IsOneOf(decision, PolicyDecision.Allow, PolicyDecision.Observe);

Clean Architecture’ta yerleşim

Domain katmanında BehaviorSpace, Intent, IntentPolicy kavramları (veya sadece referans);

Application’da IIntentModel ve Infer/Decide kullanımı;

Infrastructure’da embedding sağlayıcı (OpenAI, Mock vb.) ve isteğe bağlı persistence;

Web’de controller ve UseIntentumBehaviorObservation middleware.

Çekirdek Intentum paketleri (Core, Runtime, AI) Application veya Infrastructure’a referans verilir.

Performans ve Test

Mock: MockEmbeddingProvider ile API anahtarı olmadan yerel ve CI testleri deterministik çalışır.

Cache: MemoryEmbeddingCache veya RedisEmbeddingCache ile embedding çağrıları azaltılır.

Batch: BatchIntentModel ile birden fazla BehaviorSpace toplu işlenebilir.

Production’da gerçek sağlayıcı (OpenAI, Gemini, Mistral, Azure, Claude) kullanılır; ortam değişkenleri veya secret manager ile API anahtarları yönetilmelidir.

Ne Zaman Kullanılmamalı?

Tam deterministik mantık, her adımın zorunlu olduğu katı akışlar ve küçük/tek seferlik script’ler için Intentum gereksiz karmaşıklık getirir.

Trade-off: intent ve policy yaklaşımı esneklik ve belirsizliğe uygun; buna ihtiyaç yoksa basit kural veya doğrudan iş akışı tercih edilebilir.

Kapanış

Intentum, davranış → niyet → policy kararı zincirini .NET’te standartlaştıran bir kütüphanedir. Fraud tespiti, tekrarlı login/ödeme senaryoları veya AI destekli karar gerektiren projelerde değerlendirilebilir. Resmi doküman, örnekler ve manifesto ile derinleşmek için aşağıdaki kaynaklara bakılabilir.

Kaynak ve İleri Okuma

• Intentum – GitHub
• Intentum API Dokümantasyonu (TR)
• Kurulum, Kullanım Senaryoları, Gelişmiş Özellikler
• Manifesto ve Canon: The Intentum Manifesto