Themia.AI 0.69.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Themia.AI --version 0.69.0
                    
NuGet\Install-Package Themia.AI -Version 0.69.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Themia.AI" Version="0.69.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Themia.AI" Version="0.69.0" />
                    
Directory.Packages.props
<PackageReference Include="Themia.AI" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Themia.AI --version 0.69.0
                    
#r "nuget: Themia.AI, 0.69.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Themia.AI@0.69.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Themia.AI&version=0.69.0
                    
Install as a Cake Addin
#tool nuget:?package=Themia.AI&version=0.69.0
                    
Install as a Cake Tool

Themia.AI

A provider-agnostic AI completion client (IAiCompletionClient) with retry, failover and a total wall-clock budget, plus one typed operation built on top of it: ITextTranslationService. A reversible text masker (IAiTextMasker) is available as defence in depth for whatever gets sent.

No database, no tenant state, no IThemiaModule — there is no Themia.Modules.AI. Targets net8.0 and net10.0, and takes no dependency on Themia.Framework.*, no database package, and no ASP.NET.

A provider package does the actual HTTP call: Themia.AI.Gemini (AddThemiaAiGemini) for Google Gemini, Themia.AI.OpenAiCompatible (AddThemiaAiOpenAiCompatible) for any endpoint that speaks the OpenAI chat-completions shape — OpenAI itself, Ollama, Groq, Cerebras, LM Studio, vLLM. One provider package reaches every free-tier and self-hosted option by changing a base URL.

The first real implementation, not a port

The ezy-assets services this replaces — GeminiAICaptionService and FallbackTextTranslationService — are both placeholders: the caption service concatenates request fields with emoji into a StringBuilder ("Sprint 2: this is still a placeholder that simulates AI by formatting the context"), and the translation service returns text.Trim() unchanged. Neither repo makes a real call to any AI provider. So this package is not an upgrade over a working baseline — whatever ships here is the first real implementation either consumer has had.

Two write surfaces

  • IAiCompletionClient.CompleteAsync(AiOperation, AiPrompt, CancellationToken) — the general surface. One registration; the implementation (FailoverCompletionClient) resolves the configured model per provider per AiOperation, retries transient failures, fails over to the next configured provider, and bounds the whole call to AiOptions.TotalBudget.
  • ITextTranslationService.TranslateAsync(text, sourceLanguage, targetLanguage, CancellationToken) — the one typed operation built on top of the first. Text in, text out, no domain vocabulary.

Why translation is typed and caption is not

Translation needs nothing about what the text is — source language, target language, text. Caption generation needs to know what a property is: listing type, price, amenities, nearby points of interest. That vocabulary is application domain, and Themia.AI staying framework-neutral means it must not know it — see CLAUDE.md's framework/app boundary. An app builds a caption prompt itself as an AiPrompt and calls IAiCompletionClient.CompleteAsync(AiOperation.Completion, prompt, ct) directly; Themia.AI gives it the dispatch, retry, failover and budget, not the prompt.

AiOutcome — what a caller does with each one

AiOutcome meaning what to do
Completed success use Text
Truncated hit the output token limit; Text is real but cut mid-sentence treating this as success ships a caption ending mid-word. Raise the limit and retry, or discard
Filtered the provider's safety filter refused do not retry, do not fail over — every provider will refuse similar content. Fall back to non-AI text
ProviderLimit quota or rate limit do not retry this provider; the dispatcher fails over automatically
ProviderError transport, timeout or 5xx the dispatcher retries with backoff, then fails over, automatically

Usage is populated whenever the provider reports it, on every outcome, not only Completed — a Filtered call still consumed and was billed for its input tokens. Usage == null means "the provider did not report usage", never "this call was free".

TranslationOutcome — which ones are storable

AiOutcome TranslationOutcome Text storable?
Completed Translated the translation yes
— (same language, no provider call) SameLanguage the input, unchanged yes — correct to store as-is
Truncated Incomplete present, cut mid-sentence no
Filtered Unavailable null no
ProviderLimit (after failover is exhausted) Unavailable null no
ProviderError (after retries and failover) Unavailable null no

Two rows are easy to get wrong by taking the obvious shortcut, so both are deliberate:

  • Truncated → Incomplete gets its own member rather than folding into Translated. Its Text is non-empty, so the reflexive mapping is "this looks done" — and a caller that only checks Text != null stores a sentence that stops mid-word under a label that says it is finished.
  • Unavailable carries Text = null, never the source text. Returning the input on failure is the helpful thing to do, and it is exactly what FallbackTextTranslationService did — which is how a caller ended up storing Thai into a row labelled en-US, current and wrong, with nothing reporting it. A caller that writes row.Title = result.Text without reading Outcome first must fail immediately on Unavailable, not silently persist the wrong language. Incomplete cannot use the same protection, because its text is the point — so the two failure shapes are deliberately different: one breaks a careless caller immediately, the other requires the caller to actually read Outcome.

Empty or whitespace-only text short-circuits to SameLanguage with the input returned, without calling a provider — a call that can only return nothing still costs a call. Language codes are passed to the provider exactly as given; Themia.AI keeps no list of supported languages, because such a list goes stale and support differs per provider and per model. An unrecognised code is the provider's to reject, and its rejection surfaces as Unavailable — nothing is defaulted to a fallback language.

Masking is defence in depth, not the primary control

var masked = masker.Mask("บ้านของคุณสมชาย ติดต่อ 081-234-5678", ["สมชาย", "081-234-5678"]);
var completion = await client.CompleteAsync(AiOperation.Translation, new AiPrompt { User = masked.Text }, ct);
var restored = masked.Restore(completion.Text!);

IAiTextMasker.Mask replaces caller-supplied values with numbered, XLIFF-style tokens (<x id="1"/>) before text reaches a model, and MaskedText.Restore substitutes the originals back afterwards. The caller supplies the values to mask — Themia.AI does not detect them. Thai has no capitalisation and Thai person-name detection is unreliable, so a detector would miss names silently; an app that knows a field is contact.Name can mask it exactly, which a regex over Thai prose cannot.

Masking is not the decision that makes content safe to send. The app decides which fields are sent to a provider at all — that is the primary control. Masking only protects the specific values it is given inside text the app already decided to send, and it has real limits even there: the rest of the document can still identify someone (masking a name out of "the client is a doctor at Siriraj who wants to be near work, budget 8M" protects nobody), and pronouns degrade once a name is gone (Thai names carry gender the model uses to pick "he"/"she"; a masked name makes it guess).

Restore throws rather than returning partial text — a model that drops or duplicates a token is treated as a hard failure so the caller falls back to untranslated text (visibly not-translated) rather than showing a user a leftover <x id="3"/> (visibly broken).

Configuration and failover

services.AddThemiaAiGemini(o =>
{
    o.ApiKey           = configuration["Gemini:ApiKey"]!;
    o.CompletionModel  = "gemini-2.5-flash-lite";
    o.TranslationModel = "gemini-2.5-flash-lite";
    o.Timeout          = TimeSpan.FromSeconds(30);
});

services.AddThemiaAiOpenAiCompatible(o =>
{
    o.BaseUrl          = new Uri("http://homelab:11434/v1");
    o.CompletionModel  = "qwen2.5:7b";
    o.TranslationModel = "qwen2.5:7b";
    o.Timeout          = TimeSpan.FromSeconds(30);
});

services.AddThemiaAi(o =>
{
    // Order is preference. Every entry must be registered and must name a model for every operation.
    o.Failover = [AiProviderKeys.Gemini, AiProviderKeys.OpenAiCompatible];
});

A model name belongs to a provider, not to an operation — failing over from Gemini to an OpenAI-compatible endpoint must never send Gemini's model name to it. AiOptions.TotalBudget (default 45 seconds) bounds every retry and every failover for one CompleteAsync call; a per-provider timeout alone does not, because retries multiply it and failover repeats it. ValidateOnStart validates the whole provider × operation matrix at startup, not each setting alone — a Failover entry with no TranslationModel is a configuration that works for months and fails the first time that provider is asked to translate something.

AllowNoProvider

AddThemiaAi with an empty Failover fails at startup unless AllowNoProvider is set:

services.AddThemiaAi(o => { o.Failover = []; o.AllowNoProvider = true; });

Both behaviours are wanted by someone, which is why the choice has to be explicit. A developer with no API key wants every call to answer ProviderError / TranslationOutcome.Unavailable and the app to fall back gracefully. A production host that registered AddThemiaAi and forgot to add a provider package wants to be told at startup — without this flag it would silently get the developer's behaviour: a service that validates its configuration, answers every call, and never actually translates or completes anything.

Registration is TryAdd-based

AddThemiaAiGemini / AddThemiaAiOpenAiCompatible register their own IAiCompletionProvider; AddThemiaAi registers IAiCompletionClient, IAiTextMasker and ITextTranslationService with TryAdd*, so a caller's own registration of any of these — made before or after the call — wins, and calling AddThemiaAi more than once is a no-op the second time rather than a duplicate registration.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on Themia.AI:

Package Downloads
Themia.AI.Gemini

Google Gemini provider for Themia.AI's IAiCompletionProvider. Maps Gemini's finishReason and HTTP status onto AiOutcome, reads usageMetadata on every response that carries it, and sends the API key as an x-goog-api-key header rather than a query parameter, so it is never part of a request URI; IHttpClientFactory's default request logging is suppressed for this client as defence in depth.

Themia.AI.OpenAiCompatible

OpenAI chat-completions-shape provider for Themia.AI's IAiCompletionProvider. One implementation reaches OpenAI, Ollama, Groq, Cerebras, LM Studio and vLLM by changing BaseUrl. Maps finish_reason and HTTP status onto AiOutcome, reads usage on every response that carries it, and sends the API key as an Authorization: Bearer header.

Themia.AI.AspNetCore

Themia.AI ASP.NET Core probe — a mountable endpoint an adopter mounts in their own app to verify their own AI provider configuration works, with a no-cost configuration report and a single-call probe, both fail-closed behind an Authorize hook. Themia never holds a key and ships no deployable of its own.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.70.0 53 11/21/2026
0.69.0 99 11/18/2026
0.68.0 97 11/18/2026
0.67.2 102 11/18/2026
0.67.1 104 11/18/2026
0.67.0 111 11/17/2026
0.66.0 106 11/17/2026
0.65.0 137 11/16/2026
0.64.0 174 11/15/2026
0.63.2 148 11/15/2026
0.63.1 136 11/14/2026
0.63.0 139 11/14/2026
0.62.1 147 11/14/2026
0.62.0 158 11/14/2026
0.61.1 153 11/14/2026
0.61.0 148 11/13/2026
0.60.0 149 11/10/2026
0.59.0 140 11/10/2026
0.58.0 144 11/9/2026
0.57.2 152 11/8/2026
Loading failed