Contracts 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.
The 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:
Do not put PII in IChat.UserTrackingId. In ChatAIze.Chatbot it is forwarded to providers for abuse monitoring.
Use PinLocation.Begin for long-lived system rules and PinLocation.End for "latest state" that should stay near the end.
If you attach ImageUrls, make sure they are accessible to the provider and do not contain secrets.
Context interfaces
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:
Some 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.
Values returned by ShowFormAsync are JSON and must be treated as untrusted input.
Plugins and loading
Plugins implement IChatbotPlugin and are discovered via loader interfaces.
Discovery order in ChatAIze.Chatbot (actual host behavior):
IAsyncPluginLoader.LoadAsync
IPluginLoader.Load
First concrete IChatbotPlugin in the assembly (via Activator.CreateInstance)
Important behavior in ChatAIze.Chatbot:
Plugin types and loaders must have a public parameterless constructor (no DI at creation time).
Plugins are loaded in an isolated 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.
Plugin DLLs are copied to a temporary folder to enable hot reload/unload. Implement IDisposable/IAsyncDisposable
and avoid static event handlers to keep the load context unloadable.
Plugin authoring example (using ChatAIze.PluginApi)
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");
}
}
Functions, actions, and conditions
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):
Names are normalized to snake_case when sent to providers.
If 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:
Keep function names globally unique across plugins to avoid ambiguity.
Avoid lambdas if you rely on auto-naming; compiler-generated method names can be unstable.
Prefer simple parameter types; complex graphs do not map cleanly to provider schemas.
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.
Other parameters are bound by exact name or snake_case.
Missing/invalid values mark the action as failed.
Tips:
For action/condition settings IDs, use identifier-like keys (customer_email, timeout_seconds). Avoid : or -
because they cannot map to C# parameter names.
Keep SettingsCallback deterministic and fast; it is called frequently by the dashboard.
Use 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 execution
false to deny without a message
a string/object to deny with a reason (host may surface it to admins)
Settings and UI abstractions
Settings shape the dashboard UI and provide config values to plugins and workflows.
Core types:
ISetting: stable Id used for persistence and value binding.
Actual behavior in ChatAIze.Chatbot (important for plugin authors):
Titles and property names are normalized to snake_case for comparisons (ToSnakeLower).
Properties are stored as strings; numeric/date comparisons parse from string values.
FilterOptions.IgnoreCase and FilterOptions.IgnoreDiacritics are supported.
Sorting expects the property to exist; missing properties can throw.
Delete semantics can be soft or hard depending on host settings (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:
Do not construct your own 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.
When using numeric comparisons (GreaterThan, LessThan, ...), ensure values are parseable as numbers or dates.
Retrieval and knowledge search
IRetrievalResult and IRetrievalItem model semantic search hits.
In ChatAIze.Chatbot, IFunctionContext.SearchKnowledgeAsync returns both:
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.
Use TranslationLanguage to scope search results by language.
Localization and security
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.
Tips, warnings, and limitations (real-world notes)
Side effects: Always honor IChatContext.IsPreview and IsCommunicationSandboxed when doing external IO
(emails, HTTP calls, payments). Return simulated results in preview mode.
Schema binding: Action and function parameters are bound by name, usually in snake_case. Mismatched names lead to
missing-parameter errors. Keep parameter names aligned with setting Ids.
Plugin isolation: Plugins are loaded in an isolated AssemblyLoadContext. Sharing types across host and plugin
requires a shared assembly (such as ChatAIze.Abstractions or ChatAIze.PluginApi).
Thread safety: Plugins are effectively singletons; callbacks may execute concurrently for multiple chats.
Store per-chat state in the provided context objects, not on the plugin instance.
Not all hosts implement everything: The abstractions expose optional capabilities. Expect no-ops or exceptions for
features like CAPTCHA, feedback UI, and intelligence level switching.
Untrusted input: Settings values, form submissions, and user properties are JSON persisted data.
Validate and sanitize before use.
Related projects
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.