Sylin.Koan.AI

Sylin.Koan.AI

The AI capability ring for Koan: one business-facing client, capability-aware routing, provider composition, source health, and startup inspection.

The generated product surface owns support maturity. This page owns AI runtime setup, routing behavior, and limits.

Smallest meaningful use

Install this runtime and one provider, for example:

dotnet add package Sylin.Koan.AI
dotnet add package Sylin.Koan.AI.Connector.Ollama

using Koan.AI;
using Koan.Core;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddKoan();
using var app = builder.Build();
await app.StartAsync();

Console.WriteLine(await Client.Chat("Summarize today's orders."));

AddKoan() is the complete application bootstrap. Referenced provider modules describe their capabilities; Koan compiles the host's provider topology, activates what is actually usable, and reports the result at startup. There is no provider registration list for the application to maintain.

The application surface

Client exposes semantic operations such as Chat, Stream, Embed, Ocr, Imagine, Transcribe, Speak, Rerank, Translate, and Moderate. The application asks for an operation; the AI pipeline elects a source and adapter that truthfully advertise that capability.

string answer = await Client.Chat("Which orders need attention?");
float[] meaning = await Client.Embed("priority customer escalation");

Prompts are inspectable, immutable values and do not activate Data:

using Koan.AI.Prompt;

var prompt = Prompt.Create(p => p
    .System("You summarize orders for an operations team.")
    .Instruct("Summarize order {orderId} in one sentence.")
    .Constrain("State uncertainty explicitly."));

string summary = await Client.Chat(prompt, new { orderId = order.Id });

Reference Sylin.Koan.AI.Prompt only when the application needs an Entity-backed catalog of named versions.

Category configuration can constrain source or model without leaking provider mechanics into business code. Named sources under Koan:Ai:Sources are the advanced routing surface; ordinary applications normally need only a provider reference and, when conventions cannot locate it, that provider's exact endpoint configuration.

When one request must select both, the choices compose:

var response = await Client.Conversation()
    .WithUser("Summarize the deployment.")
    .WithSource("local-gpu") // or "local-gpu::secondary" to pin one member
    .WithModel("qwen3:8b")
    .Send();

An explicit source or member is authoritative. Koan preserves it with the explicit model or rejects a missing, disabled, or capability-incompatible choice with usable alternatives; it never silently elects another source. Without WithSource, normal capability and priority election remains unchanged.

Applications that operate a changing endpoint catalog can request IAiSourceControl. Inspect an endpoint through its provider protocol before applying it, then enable, disable, or remove the logical source without rebuilding the host:

var inspection = await sourceControl.InspectAsync(new AiSourceCandidate
{
    Provider = "ollama",
    Endpoint = "http://model-host:11434"
});

if (inspection.Available)
{
    Console.WriteLine(inspection.Version ?? "version unavailable");
    Console.WriteLine($"Installed: {string.Join(", ", inspection.Models)}");
    Console.WriteLine(inspection.ResidentModelsAvailable
        ? $"Resident: {string.Join(", ", inspection.ResidentModels)}"
        : "Residency unavailable");
}

sourceControl.Disable("maintenance-pool");
sourceControl.Remove("retired-pool", expectedOrigin: "runtime");

Available means at least one provider-owned inspection facet answered. VersionAvailable, ModelsAvailable, and ResidentModelsAvailable distinguish unavailable facts from successful empty values; Models is the installed-model catalog. Ollama inspection owns its version, tags, and process APIs. LM Studio inspection owns its OpenAI-compatible models API and reports only the facets that protocol can inspect. Inspection does not register the endpoint. Disabled and removed sources leave routing and health probing immediately.

Host and failure contract

• Client.IsAvailable and Client.TryResolve() are optional probes. They return absence for a missing or disposed host.
• Required operations throw KoanHostContextException when no live composed AI pipeline exists.
• Referencing the AI runtime without a usable provider is allowed; invoking an unsupported operation is not.
• Explicit provider configuration is intent and fails startup when invalid. Automatic candidates may be absent without making the application unhealthy.
• AI source health is always present alongside other Koan readiness components once AI is active. It is noncritical by default: an unavailable provider remains visible as Koan.AI without taking an otherwise healthy application offline. Members that have not completed a probe report unknown; they are never counted as healthy.
• Provider HTTP/model errors and cancellation remain visible to the caller.

Provider packages document their exact discovery, configuration, and guarantee boundaries. See TECHNICAL.md for the compilation and routing model.