Abstract classes, interfaces, and enums shared across ChatAIze projects for better interoperability.
$ dotnet add package ChatAIze.AbstractionsContracts shared across the ChatAIze ecosystem. This package is intentionally implementation-free: it defines interfaces, enums, and conventions that let hosts, plugins, and tooling interoperate without taking direct dependencies on each other.
It is used in:
ChatAIze.Chatbot (the host)ChatAIze.GenerativeCS (LLM/tool schema + execution)ChatAIze.PluginApi (concrete implementations for plugin authors)law-firm-pluginIf you are building a ChatAIze host, plugin, or integration, this is the set of contracts you implement and/or consume.
dotnet add package ChatAIze.Abstractions
Target framework: net10.0. If your project targets an earlier runtime, reference the project directly or multi-target accordingly.
IChat, IChatMessage, IFunctionCall, IFunctionResult, ChatRole, PinLocationIChatbotContext, IChatContext, IUserContext, IFunctionContext, IActionContext, IConditionContextIChatbotPlugin, IPluginLoader, IAsyncPluginLoader, IPluginSettingsISetting and specific setting types plus UI enums for styleIDatabaseManager, IDatabase, IDatabaseItem, filtering/sorting + exceptionsIRetrievalItemIRetrievalResultTranslationLanguage, SecurityRoleThe chat interfaces model a provider-agnostic transcript with support for tool calls.
IChat<TMessage, TFunctionCall, TFunctionResult> defines the collection plus FromXxxAsync helpers to construct messages.
In ChatAIze.Chatbot, these methods create messages but do not persist them, so callers still add them to storage.IChatMessage<TFunctionCall, TFunctionResult> represents a single turn. A message can hold text, tool calls, or a tool result.ChatRole mirrors common LLM roles: system, user, assistant, tool.PinLocation hints how a host should keep messages when trimming context for token budgets.Tips:
IChat.UserTrackingId. In ChatAIze.Chatbot it is forwarded to providers for abuse monitoring.PinLocation.Begin for long-lived system rules and PinLocation.End for "latest state" that should stay near the end.ImageUrls, make sure they are accessible to the provider and do not contain secrets.Contexts are the "ambient services" a host provides to plugins and workflow callbacks.
IChatbotContext: host services outside a specific chat (settings + databases + logging).IChatContext: adds chat-specific fields such as ChatId, User, IsPreview, IsDebugModeOn,
and IsCommunicationSandboxed. Use these flags to guard side effects.IUserContext: identity, locale, and per-user storage (GetPropertyAsync / SetPropertyAsync).IFunctionContext: adds prompt/quick replies, knowledge search, status/progress, and UI prompts.IActionContext: extends IFunctionContext with action execution state, placeholders, and early-exit control.IConditionContext: intentionally adds no extra APIs; use it only for checks.Warnings and limitations:
IFunctionContext APIs are best-effort and may be no-ops or throw. In ChatAIze.Chatbot, SetIntelligenceLevel
currently throws NotImplementedException.ShowCaptchaAsync, ShowFeedbackAsync, and VerifyEmailAsync are host features; always handle failures gracefully.ShowFormAsync are JSON and must be treated as untrusted input.Plugins implement IChatbotPlugin and are discovered via loader interfaces.
Discovery order in ChatAIze.Chatbot (actual host behavior):
IAsyncPluginLoader.LoadAsyncIPluginLoader.LoadIChatbotPlugin in the assembly (via Activator.CreateInstance)Important behavior in ChatAIze.Chatbot:
AssemblyLoadContext; only a set of shared assemblies are loaded from the default context
(including ChatAIze.Abstractions, ChatAIze.PluginApi, ChatAIze.GenerativeCS, ChatAIze.Utilities, and
Microsoft.Extensions.*). Other dependencies are private to the plugin.IDisposable/IAsyncDisposable
and avoid static event handlers to keep the load context unloadable.using ChatAIze.Abstractions.Chat;
using ChatAIze.Abstractions.Plugins;
using ChatAIze.PluginApi;
using ChatAIze.PluginApi.Settings;
public sealed class Loader : IPluginLoader
{
public IChatbotPlugin Load()
{
var plugin = new ChatbotPlugin
{
Id = "acme:orders",
Title = "Orders",
Version = new Version(1, 0, 0),
};
plugin.AddFunction(new ChatFunction("get_order_status")
{
Description = "Returns the status of an order by id.",
Callback = GetOrderStatusAsync
});
var action = new FunctionAction(
id: "acme:actions.create_order",
title: "Create Order",
callback: CreateOrderAsync);
action.AddStringSetting(id: "customer_email", title: "Customer Email");
action.AddStringSetting(id: "sku", title: "SKU");
plugin.AddAction(action);
return plugin;
}
private static Task<string> GetOrderStatusAsync(IFunctionContext ctx, string orderId, CancellationToken ct)
=> Task.FromResult($"Order {orderId}: shipped");
private static async Task CreateOrderAsync(IActionContext ctx, string customerEmail, string sku, CancellationToken ct)
{
if (ctx.IsPreview || ctx.IsCommunicationSandboxed)
{
ctx.SetActionResult(isSuccess: true, "Simulated order creation.");
return;
}
// Real side effect here.
ctx.SetActionResult(isSuccess: true, "Order created.");
ctx.SetPlaceholder("order_id", "1234");
}
}IChatFunction (LLM tools)Functions are surfaced to the model through ChatAIze.GenerativeCS and can also power workflows.
Key behaviors (from the contracts and host usage):
Parameters is null, hosts often infer a schema from Callback via reflection.RequiresDoubleCheck is a safety flag; ChatAIze.GenerativeCS implements it by forcing a double tool call.Tips:
IFunctionAction (workflow steps)Actions are used in the ChatAIze dashboard function builder to compose workflows. The host binds action settings into the callback parameters.
Binding rules in the default host (ChatAIze.Utilities.Extensions.DelegateExtensions):
IActionContext and CancellationToken parameters are injected by type.Tips:
customer_email, timeout_seconds). Avoid : or -
because they cannot map to C# parameter names.SettingsCallback deterministic and fast; it is called frequently by the dashboard.PlaceholdersCallback to declare outputs. In ChatAIze.Chatbot placeholder ids are normalized to snake_case and
duplicates are suffixed (order_id, order_id_2, ...).IFunctionCondition (guards)Conditions are evaluated before running a workflow. The callback may return:
true to allow executionfalse to deny without a messageSettings shape the dashboard UI and provide config values to plugins and workflows.
Core types:
ISetting: stable Id used for persistence and value binding.ISettingsSection, ISettingsGroup, ISettingsContainer.IStringSetting, IBooleanSetting, IIntegerSetting, IDecimalSetting, ISelectionSetting,
IListSetting, IMapSetting, IDateTimeSetting.TextFieldType, SelectionSettingStyle, IntegerSettingStyle, BooleanSettingStyle, DateTimeSettingStyle.Conventions used in ChatAIze.Chatbot:
Id.IDefaultValueObject.DefaultValueObject is used to fill missing values in action/condition placements.Tips:
myplugin:api_key) to avoid collisions.Id is a breaking change for persisted data.IsDisabled to gray out settings, but do not rely on it for security.ISettingsButton.Callback runs on the server; keep it idempotent and respect cancellation tokens.ChatAIze includes a lightweight, host-managed database abstraction for structured records.
Key contracts:
IDatabaseManager provides CRUD, querying, and filtering.IDatabase and IDatabaseItem are the records.IDatabaseFilter + IDatabaseSorting provide query shaping.DuplicateTitleException, InvalidTitleException, PropertyException.Actual behavior in ChatAIze.Chatbot (important for plugin authors):
ToSnakeLower).FilterOptions.IgnoreCase and FilterOptions.IgnoreDiacritics are supported.EnableTrash).Example query:
var db = await context.Databases.FindDatabaseByTitleAsync("Contacts", ct);
if (db is null) return;
var filter = new DatabaseFilter("email", FilterType.Equal, "user@example.com", FilterOptions.IgnoreCase);
var contact = await context.Databases.GetFirstItemAsync(db, sorting: null, cancellationToken: ct, filters: filter);Warnings:
IDatabase or IDatabaseItem implementations and pass them into a host manager. In
ChatAIze.Chatbot, the manager expects its own CustomDatabase and DatabaseItem types and will throw otherwise.GreaterThan, LessThan, ...), ensure values are parseable as numbers or dates.IRetrievalResult and IRetrievalItem model semantic search hits.
In ChatAIze.Chatbot, IFunctionContext.SearchKnowledgeAsync returns both:
Items: displayable snippets (title, description, content, optional source URL).ChunkIds: internal identifiers for the exact chunks used. Pass them back as ignoredChunkIds to avoid repeats.Tips:
IRetrievalItem.Content is often truncated. Call GetDocumentContentAsync for the full content.TranslationLanguage to scope search results by language.TranslationLanguage is a ChatAIze-specific enum (not BCP-47). Hosts typically provide mapping from locale codes.
ChatAIze.Chatbot uses a dedicated converter to map en-US, fr-CA, etc. to enum values.SecurityRole controls dashboard access levels and can be used in conditions/actions to gate admin-only operations.IChatContext.IsPreview and IsCommunicationSandboxed when doing external IO
(emails, HTTP calls, payments). Return simulated results in preview mode.Ids.AssemblyLoadContext. Sharing types across host and plugin
requires a shared assembly (such as ChatAIze.Abstractions or ChatAIze.PluginApi).ChatAIze.Chatbot: reference host implementation of these interfaces.ChatAIze.PluginApi: convenient concrete implementations for plugin authors.ChatAIze.GenerativeCS: tool schema generation and provider integration.ChatAIze.Utilities: argument binding helpers (DelegateExtensions) used by the host.GPL-3.0-or-later. See LICENSE for details.