Kurulum (TR)

Bu sayfayı neden okuyorsunuz? Bu sayfa Intentum'u projenize ekleyip ilk çalışan akışı (gözlemle → çıkar → karar ver) kurmanızı sağlar. Gereksinimler, paket kurulumu ve Intentum’u uçtan uca çalıştırabilmen için minimal bir ilk proje adımlarını anlatır.

Gereksinimler

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

Paket kurulumu (NuGet)

Çekirdek (behavior space, intent ve policy için gerekli):

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

Sağlayıcılar (opsiyonel; gerçek embedding API’leri için bir veya daha fazlasını seç):

dotnet add package Intentum.AI.OpenAI
dotnet add package Intentum.AI.Gemini
dotnet add package Intentum.AI.Mistral
dotnet add package Intentum.AI.AzureOpenAI
dotnet add package Intentum.AI.Claude

İstersen Intentum.Providers ekleyerek Core, Runtime, AI ve tüm sağlayıcı paketlerini tek seferde alabilirsin: dotnet add package Intentum.Providers.

Sağlayıcı eklemezsen yerel çalıştırma için MockEmbeddingProvider (Intentum.AI içinde) kullan — API anahtarı gerekmez.

İlk proje: minimal konsol uygulaması

Bu örnek ne yapar? Ahmet kullanıcısı 1 dakika içinde 3 kez giriş denedi (2 başarısız, 1 başarılı), ardından "submit" aksiyonunu tetikledi. Kod bu olayları kaydeder, niyet ve güven çıkarır, basit bir policy ile Allow veya Observe kararı verir.

Doğru yaptığınızı nasıl anlarsınız? dotnet run sonrası konsolda bir güven seviyesi (örn. High, Medium) ve bir karar (Allow veya Observe) görürsünüz.

Konsol uygulaması oluştur (yoksa):

dotnet new console -n MyIntentumApp -o MyIntentumApp
cd MyIntentumApp

Çekirdek paketleri ekle (yukarıdaki gibi).
Program.cs içeriğini minimal akışla değiştir:

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

// 1) Davranış: ne oldu?
var space = new BehaviorSpace()
    .Observe("user", "login")
    .Observe("user", "retry")
    .Observe("user", "submit");

// 2) Intent çıkar (mock sağlayıcı = API anahtarı yok)
var model = new LlmIntentModel(
    new MockEmbeddingProvider(),
    new SimpleAverageSimilarityEngine());
var intent = model.Infer(space);

// 3) Basit bir policy ile karar ver
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}");

Çalıştır
```
dotnet run
```

Bir güven seviyesi ve karar (örn. Allow veya Observe) görmelisin. Sonra: Senaryolar ile daha fazla kural, Sağlayıcılar ile gerçek sağlayıcı, API Referansı ile tüm tipler.

Gerçek sağlayıcı kullanımı (örn. OpenAI)

Sağlayıcı paketini ekle: dotnet add package Intentum.AI.OpenAI.
Ortam değişkenlerini ayarla (örn. OPENAI_API_KEY, OPENAI_EMBEDDING_MODEL). Bkz. Sağlayıcılar.
Mock’u gerçek sağlayıcı ve options ile değiştir:

using Intentum.AI.OpenAI;

var options = OpenAIOptions.FromEnvironment();
var httpClient = new HttpClient { BaseAddress = new Uri(options.BaseUrl ?? "https://api.openai.com/v1/") };
// Auth header ekle, sonra:
var embeddingProvider = new OpenAIEmbeddingProvider(options, httpClient);
var model = new LlmIntentModel(embeddingProvider, new SimpleAverageSimilarityEngine());

DI (örn. ASP.NET Core) için services.AddIntentumOpenAI(options) kullan ve sağlayıcıyı inject et. Bkz. Sağlayıcılar.

Şablondan oluştur (dotnet new)

dotnet new ve Intentum şablonlarıyla (repo templates klasöründen bir kez kur) önceden yapılandırılmış bir projeden başlayabilirsin:

# Repo kökünden: şablonları kur
dotnet new install ./templates/intentum-webapi
dotnet new install ./templates/intentum-backgroundservice
dotnet new install ./templates/intentum-function

Sonra yeni proje oluştur:

Şablon	Açıklama
intentum-webapi	Intentum’lu minimal ASP.NET Core Web API: infer endpoint, health check, Mock sağlayıcı.
intentum-backgroundservice	MemoryBehaviorStreamConsumer ve IntentStreamWorker ile .NET Worker Service; behavior event batch’lerini intent modeli ve policy üzerinden işler.
intentum-function	HTTP tetiklemeli InferIntent fonksiyonu, Mock model ve policy ile Azure Functions v4 (isolated worker).

Örnek:

dotnet new intentum-webapi -n MyIntentumApi -o MyIntentumApi
cd MyIntentumApi
dotnet run

Policy Store, Context-Aware Policy, Multi-Stage Model ve diğer uzantılar için Gelişmiş Özellikler bölümüne bakın.

Ortam değişkenleri (özet)

Sadece gerçek HTTP adapter kullanırken ayarla:

Sağlayıcı	Ana değişkenler
OpenAI	`OPENAI_API_KEY`, `OPENAI_EMBEDDING_MODEL`, `OPENAI_BASE_URL`
Gemini	`GEMINI_API_KEY`, `GEMINI_EMBEDDING_MODEL`, `GEMINI_BASE_URL`
Mistral	`MISTRAL_API_KEY`, `MISTRAL_EMBEDDING_MODEL`, `MISTRAL_BASE_URL`
Azure OpenAI	`AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_EMBEDDING_DEPLOYMENT`, `AZURE_OPENAI_API_VERSION`
Claude	`CLAUDE_API_KEY`, `CLAUDE_MODEL`, `CLAUDE_BASE_URL` vb.

Detay ve örnekler: Sağlayıcılar.

Yerel geliştirme (örn. entegrasyon testleri veya VerifyAI) için .env kullanabilirsiniz: .env.example'ı .env olarak kopyalayın, en az bir sağlayıcının anahtarını (OpenAI, Mistral, Gemini, Azure) set edin ve dotnet run --project samples/Intentum.VerifyAI veya sağlayıcı script'lerini (./scripts/run-integration-tests.sh, run-mistral-integration-tests.sh vb.) çalıştırın. Bkz. Yerel entegrasyon testleri. .env asla commit edilmez; .gitignore'dadır.

Repo yapısı

Çözüm birçok paket ve iki örnek uygulama içerir.

Çekirdek ve runtime (behavior space, intent, policy için gerekli):

Intentum.Core — BehaviorSpace, Intent (Reasoning ile), BehaviorEvent, BehaviorSpaceBuilder, ToVectorOptions, BatchIntentModel, RuleBasedIntentModel, ChainedIntentModel
Intentum.Runtime — IntentPolicy, IntentPolicyBuilder, PolicyDecision, IRateLimiter, MemoryRateLimiter
Intentum.AI — LlmIntentModel, embedding cache, similarity engine'ler (SimpleAverage, TimeDecay, Cosine, Composite), ITimeAwareSimilarityEngine

AI sağlayıcıları (opsiyonel; gerçek embedding için bir veya daha fazlası):

Intentum.AI.OpenAI, Intentum.AI.Gemini, Intentum.AI.Mistral, Intentum.AI.AzureOpenAI, Intentum.AI.Claude

Uzantılar (ihtiyaca göre eklenir):

Intentum.AspNetCore — Davranış gözlem middleware'i, health check'ler
Intentum.Testing — TestHelpers, BehaviorSpace, Intent, PolicyDecision assertion'ları
Intentum.Observability — Intentum işlemleri için OpenTelemetry metrikleri
Intentum.Logging — Intentum için Serilog entegrasyonu
Intentum.Persistence — IBehaviorSpaceRepository, IIntentHistoryRepository
Intentum.Persistence.EntityFramework — EF Core implementasyonu (SQL Server, SQLite, in-memory)
Intentum.Persistence.Redis — Redis tabanlı behavior space ve intent history; AddIntentumPersistenceRedis(redis, keyPrefix?)
Intentum.Persistence.MongoDB — MongoDB tabanlı behavior space ve intent history; AddIntentumPersistenceMongoDB(database, collectionNames?)
Intentum.Analytics — IIntentAnalytics: trendler, karar dağılımı, anomali tespiti, JSON/CSV export
Intentum.CodeGen — CQRS + Intentum scaffold, YAML/JSON spec doğrulama

Örnekler:

samples/Intentum.Sample — Konsol: ESG, Carbon, EU Green Bond, workflow, klasik (ödeme, destek, e‑ticaret), fluent API, caching, batch, rate limiting demo
samples/Intentum.Sample.Blazor — Blazor WebAssembly/Server örnek uygulama (web UI + API): Overview, Commerce, Explain, FraudLive, Sustainability, Timeline, PolicyLab, Sandbox, Settings, Signals, Graph, Heatmap sayfaları; Carbon, Greenwashing, OrderPlacement CQRS; intent infer/explain/explain-tree, greenwashing tespiti, Dashboard, analytics, timeline, playground compare; SSE inference broadcast, dolandırıcılık ve sürdürülebilirlik simülasyonu. Çalıştırma: dotnet run --project samples/Intentum.Sample.Blazor. Bkz. Greenwashing tespiti (how-to).

Repo sample'ını derle ve çalıştır

Reponun kökünden:

dotnet build Intentum.slnx

Konsol örneği (senaryolar, batch, rate limit demo):

dotnet run --project samples/Intentum.Sample

ESG, Carbon, EU Green Bond, workflow ve klasik (ödeme, destek, e‑ticaret) senaryolarını çalıştırır. Varsayılan mock embedding kullanır (API anahtarı gerekmez); çıktıda AI: Mock (no API key) → similarity → confidence → policy görürsün.

Gerçek AI denemek için: OPENAI_API_KEY (ve isteğe bağlı OPENAI_EMBEDDING_MODEL) ortam değişkenini ayarla; örnek OpenAI embedding kullanır. Bkz. Sağlayıcılar.

Web örneği (Blazor) (API + UI, intent infer, explain, greenwashing, Dashboard, analytics):

dotnet run --project samples/Intentum.Sample.Blazor

UI: http://localhost:5018/ (veya launchSettings.json'daki port) — Overview, Commerce, Explain, FraudLive, Sustainability, Timeline, PolicyLab, Sandbox, Settings, Signals, Graph, Heatmap; Dashboard (analytics, son çıkarımlar, son greenwashing analizleri)
API dokümanları (Scalar): http://localhost:5018/scalar
Endpoint'ler:
- Carbon: POST /api/carbon/calculate, GET /api/carbon/report/{id}
- Orders: POST /api/orders
- Intent: POST /api/intent/infer (body: { "events": [ { "actor": "user", "action": "login" }, ... ] }), POST /api/intent/explain (aynı body; sinyal katkıları döner), POST /api/intent/explain-tree (karar ağacı), POST /api/intent/playground/compare (model karşılaştırma)
- Greenwashing: POST /api/greenwashing/analyze (body: { "report": "...", "sourceType": "Report", "language": "tr", "imageBase64": null }), GET /api/greenwashing/recent?limit=15
- Analytics: GET /api/intent/analytics/summary, GET /api/intent/history, GET /api/intent/analytics/timeline/{entityId}, GET /api/intent/analytics/export/json, GET /api/intent/analytics/export/csv
- Health: /health

Kurulumu tamamladıysanız → Senaryolar veya API Referansı.

Yerel NuGet’ten kurulum (geliştirme)

Intentum’u kaynaktan derleyip yerel paket referansı vermek istersen:

dotnet pack Intentum.slnx -c Release
dotnet nuget add source /path/to/Intentum/src/Intentum.Core/bin/Release -n IntentumLocal
dotnet add package Intentum.Core --source IntentumLocal

Diğer projeler (Intentum.Runtime, Intentum.AI vb.) için gerekirse tekrarla.

Testler ve benchmark'lar

Birim ve contract testleri: Repo kökünden dotnet test tests/Intentum.Tests/Intentum.Tests.csproj. Bkz. Test.
Entegrasyon testleri ve VerifyAI (yalnızca yerel): .env'de en az bir sağlayıcının anahtarını set edin (bkz. .env.example), ardından dotnet run --project samples/Intentum.VerifyAI veya sağlayıcı script'lerini (./scripts/run-integration-tests.sh, run-mistral-integration-tests.sh, run-gemini-integration-tests.sh, run-azure-integration-tests.sh) çalıştırın. Bkz. Yerel entegrasyon testleri.
Benchmark'lar: Gecikme ve throughput için dotnet run --project benchmarks/Intentum.Benchmarks/Intentum.Benchmarks.csproj -c Release çalıştırın. Sonuçlar BenchmarkDotNet.Artifacts/results/ altına yazılır. Bkz. benchmarks/README.md ve Case studies.

Table of Contents