Unicorb 0.9.17-alpha

Unicorb

State-machine engine for bots. It provides registries for commands, states, handlers and extractors, plus an update processing pipeline.

The package is transport-neutral. The host decides where updates come from and where responses are sent.

TFM: net9.0, net10.0

The API may change before version 1.0.0.

Install

dotnet add package Unicorb

Quick Start

builder.Services.AddUnicorb(o =>
{
    o.Registries(r => r.ScanFrom<MyMarker>());
});

ScanFrom<T> scans one assembly for commands, states, handlers and extractors.

Use explicit scanning when you need more control:

builder.Services.AddUnicorb(o => o.Registries(r =>
{
    r.ScanCommandsFrom<MyMarker>();
    r.ScanStatesFrom<MyMarker>();
    r.ScanHandlersFrom<MyMarker>();
    r.ScanExtractorsFrom<MyMarker>();
}));

Dialog Model

• InteractionState waits for user input.
• TransitionState moves to the next step without user input.
• CommandHandler, InteractionHandler and TransitionHandler process dialog steps.
• IInputExtractor<TUpdate, TInput> converts a transport update into handler input.
• StateContext stores session variables.

Session snapshots are stored by key:

public sealed record SessionKey(string Platform, string Member);

Platform separates transports such as telegram, max and playground. Member identifies the session.

Validate Wiring

After app.Build(), validate that handlers and extractors are connected:

var app = builder.Build();
app.Services.ValidateUnicorb<PlaygroundUpdate>();

Overrides

• Add a custom extractor with ScanExtractorsFrom<MyMarker>() after the bridge marker.
• If multiple extractors match the same (TUpdate, TInput) pair, the last one wins.
• Register a custom slash-command parser before AddUnicorb.
• Register a custom ISnapshotStore or ISessionFactory before AddUnicorb.
• The default InMemorySnapshotStore is for get-started and local dev only; use a persistent store in production.

builder.Services.AddSingleton<ICommandInvocationParser, MyCommandParser>();
builder.Services.AddUnicorb(o => o.Registries(r => r.ScanFrom<MyMarker>()));

Bridge Packages

Minimal Playground stack:

builder.Services.AddUnicorb(o => o.Registries(r =>
{
    r.ScanHandlersFrom<MyMarker>();
    r.ScanStatesFrom<MyMarker>();
    r.ScanCommandsFrom<MyMarker>();
    r.ScanExtractorsFrom<PlaygroundAssemblyMarker>();
}));

builder.Services.AddPlayground();
builder.Services.AddPlaygroundBridge();

var app = builder.Build();
app.Services.ValidateUnicorb<PlaygroundUpdate>();
app.UsePlayground();

Demo

dotnet run --project Unicorb.Demo