MentorAgent.Abstractions 1.0.0-preview.5

MentorAgent.Abstractions

Preview Release — MentorAgent is currently in public preview. APIs may change before the stable release.

You do not need to install this package directly. It is included automatically as a transitive dependency of MentorAgent and MentorAgent.Blazor.

This package is the shared foundation of the MentorAgent family. It contains all the contracts, models, and UI components shared between the server-side and client-side packages — with no AI or ASP.NET Core server dependencies, making it fully compatible with Blazor WebAssembly.

Table of Contents

• Package Family
• What's included
  • Interfaces
  • Models
  • Enums
  • UI Components (Razor)
  • Core
• Component parameter reference
• Static assets — CSS and JS
• When you actually touch this package
• Why a separate package?
• Requirements
• Related Packages
• License

Package Family

What's included

Interfaces

Models

Enums

UI Components (Razor)

All MentorAgent UI components live here so they work identically in both Blazor Server and Blazor WASM:

Core

Component parameter reference

Every component is presentational in the sense that matters: it takes its data through parameters and raises callbacks out, never calling the AI itself. That is what lets the identical component serve Blazor Server (data from DI) and WebAssembly (data over HTTP), and it is what lets you compose the parts on your own pages instead of taking the whole widget.

ChatWidget is the exception — it is the assembled widget and resolves IMentorOrchestrator, IMentorStateService and navigation for itself.

They still need DI. Every component injects IOptions<MentorWidgetOptions>, MentorLocalizer or both, so AddMentorAgent() / AddMentorAgentBlazor() must have run in that host. Rendering MessageBubble on a page of an app that never registered MentorAgent throws at build-render time, not at first interaction.

ChatWidget

<ChatWidget>
    <CardTemplate Context="card">
        @if (card.Kind == "order") { <OrderCard Card="card" /> }
        else                       { <MentorCardView Card="card" /> }
    </CardTemplate>
</ChatWidget>

Everything else about the widget comes from MentorWidgetOptions in DI, not from parameters — see the option tables in the MentorAgent or MentorAgent.Blazor README, depending on which host you use.

MentorDashboard

The Refresh button is always rendered; OnRefresh only decides whether anything of yours runs when it is pressed. With no data at all the component renders its empty state rather than throwing.

Its resolution order when Snapshot is null is: an external IMentorMetricsStore.QueryAsync() first (so a Prometheus/Azure Monitor aggregate wins), then the live in-RAM IMentorMetrics snapshot.

@* Blazor Server — no parameters needed *@
<MentorDashboard />

@* WASM — you own the fetch *@
<MentorDashboard Snapshot="_snapshot"
                 OnRefresh="Reload"
                 Currency="€"
                 Language="MentorLanguage.Italian" />

MentorCardView

MessageBubble

ChatInput

OnboardingTour

OnNavigate and OnAsk are engagement, not dismissal: the host is expected to suspend the tour and resume at the next step, not mark it seen. ChatWidget already does this.

ConfirmationBanner

WelcomePanel

RagSourcePanel

Status badges

bool? in ServerStatus is three-valued on purpose: true connected, false failed, null not yet probed. Rendering null as "failed" would show a red badge during startup.

TypingIndicator

No parameters — animated dots. Show it while a turn is in flight and nothing has streamed yet.

Static assets — CSS and JS

The stylesheet and the JavaScript layer ship in this package, not in MentorAgent:

_content/MentorAgent.Abstractions/css/MentorAgent.css
_content/MentorAgent.Abstractions/js/MentorAgent.js
_content/MentorAgent.Abstractions/IconMA.png     ← default avatar

ChatWidget injects the first two itself through <HeadContent>, so a Blazor Server or Blazor Web App host needs no markup. A standalone WASM host references them manually in index.html instead — and neither file is fingerprinted, so the ?v= query string is the cache buster and you must bump it by hand after changing either. A stale MentorAgent.js fails silently and looks like missing features rather than a caching problem.

The JS layer covers text-to-speech (sentence-queued, barge-in, hands-free), speech recognition, the image composer (upload, paste, drag & drop, client-side downscaling) and localStorage helpers. It is called through IJSRuntime by the components; there is no supported way to call it directly.

For the complete CSS variable reference — palette, widget size, fonts, the dashboard and chart colours — see Widget customization → CSS variables in the MentorAgent README. The variables are defined here but documented there, next to the options that set them.

When you actually touch this package

Most of the time you never reference these types by name — MentorAgent and MentorAgent.Blazor wire them for you. Three cases where you do:

1. Rendering the admin dashboard yourself. MentorDashboard is presentational, so the same component works in-process and over HTTP. In Blazor Server, inject the metrics; in WASM, fetch the snapshot from the admin endpoint:

@* Blazor Server — in-process. It resolves the metrics itself; no parameters needed. *@
<MentorDashboard />

@* WASM — over HTTP. No MentorAgent DI here, so pass the language explicitly. *@
@inject HttpClient Http
<MentorDashboard Snapshot="_snapshot" Language="MentorLanguage.Italian" />
@code {
    MentorMetricsSnapshot? _snapshot;
    protected override async Task OnInitializedAsync() =>
        _snapshot = await Http.GetFromJsonAsync<MentorMetricsSnapshot>("/mentor/admin/metrics");
}

Put it behind authorization. The snapshot is operator data — cost, volumes, top actions — and must never appear on an end-user page.

2. Persisting or aggregating metrics. Implement IMentorMetricsStore and register it before AddMentorAgent() / AddMentorAgentServer(). Without one the snapshot lives in RAM and resets on restart; with one you get durability, or you can serve an external aggregate instead:

Every method has a default no-op implementation, because the two scenarios use different halves of the contract — implement only the one you need:

// (A) Local durability — restore totals at startup, persist periodically and on shutdown.
//     QueryAsync stays default (null) so the dashboard keeps serving the live in-RAM snapshot.
public sealed class FileMetricsStore : IMentorMetricsStore
{
    public Task<MentorMetricsSnapshot?> LoadForSeedAsync(CancellationToken ct = default) => /* read  */;
    public Task SaveAsync(MentorMetricsSnapshot s, CancellationToken ct = default)       => /* write */;
}

// (B) External source — serve the aggregate your OpenTelemetry export already pushed to
//     Prometheus / Azure Monitor (multi-instance, historical). Nothing to seed, nothing to save.
public sealed class PrometheusMetricsStore : IMentorMetricsStore
{
    public Task<MentorMetricsSnapshot?> QueryAsync(CancellationToken ct = default) => /* query */;
}

builder.Services.AddSingleton<IMentorMetricsStore, FileMetricsStore>();   // BEFORE AddMentorAgent()

3. Building your own composer or transcript. MentorUserMessage + MentorAttachment are the shape of a user turn, and IMentorOrchestrator.SendMessageAsync(text, attachments) is what consumes it — so a custom input control can replace ChatInput without touching the orchestration layer.

Working implementations of all three ship in the MentorAgentSample repository.

Why a separate package?

MentorAgent (server) depends on Microsoft.Agents.AI, ModelContextProtocol.AspNetCore, and other server-only packages that are not compatible with Blazor WebAssembly. MentorAgent.Blazor (WASM) cannot reference MentorAgent directly.

MentorAgent.Abstractions contains only WebAssembly-safe dependencies:

• Microsoft.AspNetCore.Components.Web
• Microsoft.AspNetCore.Components.Authorization
• Microsoft.Extensions.AI

Both MentorAgent and MentorAgent.Blazor reference MentorAgent.Abstractions — sharing interfaces, models, and UI components without cross-contaminating dependencies.

The practical rule: anything that must run in the browser goes here. If you are adding a type and it needs Microsoft.Agents.AI, an HttpContext, or the file system, it does not belong in this package — the WASM build will not fail at compile time, it will fail at runtime in the browser.

Requirements

• .NET 10.0 or later
• Microsoft.AspNetCore.Components.Web 10.0.3
• Microsoft.AspNetCore.Components.Authorization 10.0.3
• Microsoft.Extensions.AI 10.6.0

No AI provider, no server packages, no JavaScript dependencies beyond the browser's own Speech and File APIs.

Related Packages

License

MIT — the full text ships in the repository's LICENSE file.